bump: version 0.57.36 → 0.57.37

chore(deps): update helm release ollama to v1.41.0

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

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 
       - name: Get version from tag
         id: tag
@@ -35,18 +35,18 @@ jobs:
           echo "Version validated: $INFO_VERSION"
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 22
 
       - name: Setup PHP
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # v2
         with:
           php-version: 8.1
           coverage: none
 
       - name: Checkout Nextcloud server (for signing)
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           repository: nextcloud/server
           ref: stable30
@@ -70,7 +70,7 @@ jobs:
         run: make appstore server_dir=${{ github.workspace }}/server
 
       - name: Create GitHub release and attach tarball
-        uses: svenstaro/upload-release-action@v2
+        uses: svenstaro/upload-release-action@6b7fa9f267e90b50a19fef07b3596790bb941741 # v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
           file: ${{ env.APP_DIR }}/build/artifacts/${{ env.APP_NAME }}.tar.gz
@@ -80,7 +80,7 @@ jobs:
           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@v1.0.4
+        uses: R0Wi/nextcloud-appstore-push-action@9244bb5445776688cfe90fa1903ea8dff95b0c28 # v1.0.4
         with:
           app_name: ${{ env.APP_NAME }}
           appstore_token: ${{ secrets.APPSTORE_TOKEN }}

.github/workflows/astrolabe-ci.yml

@@ -1,24 +1,24 @@
-# Consolidated CI workflow for Astroglobe Nextcloud app
+# Consolidated CI workflow for Astrolabe Nextcloud app
 #
-# Runs on PRs that modify the astroglobe directory
+# Runs on PRs that modify the astrolabe directory
 # Based on Nextcloud app skeleton workflows
 #
 # SPDX-FileCopyrightText: 2025 Nextcloud MCP Server contributors
 # SPDX-License-Identifier: MIT
 
-name: Astroglobe CI
+name: Astrolabe CI
 
 on:
   pull_request:
     paths:
-      - 'third_party/astroglobe/**'
-      - '.github/workflows/astroglobe-ci.yml'
+      - 'third_party/astrolabe/**'
+      - '.github/workflows/astrolabe-ci.yml'
 
 permissions:
   contents: read
 
 concurrency:
-  group: astroglobe-ci-${{ github.head_ref || github.run_id }}
+  group: astrolabe-ci-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
@@ -37,18 +37,18 @@ jobs:
         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'
+              - 'third_party/astrolabe/src/**'
+              - 'third_party/astrolabe/package.json'
+              - 'third_party/astrolabe/package-lock.json'
+              - 'third_party/astrolabe/vite.config.js'
+              - 'third_party/astrolabe/**/*.js'
+              - 'third_party/astrolabe/**/*.ts'
+              - 'third_party/astrolabe/**/*.vue'
             php:
-              - 'third_party/astroglobe/lib/**'
-              - 'third_party/astroglobe/appinfo/**'
-              - 'third_party/astroglobe/composer.json'
-              - 'third_party/astroglobe/psalm.xml'
+              - 'third_party/astrolabe/lib/**'
+              - 'third_party/astrolabe/appinfo/**'
+              - 'third_party/astrolabe/composer.json'
+              - 'third_party/astrolabe/psalm.xml'
 
   # Node.js build and lint
   node-build:
@@ -58,7 +58,7 @@ jobs:
     name: Node.js build
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -67,7 +67,7 @@ jobs:
         uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
         id: versions
         with:
-          path: third_party/astroglobe
+          path: third_party/astrolabe
           fallbackNode: '^20'
           fallbackNpm: '^10'
 
@@ -99,7 +99,7 @@ jobs:
     name: ESLint
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -108,7 +108,7 @@ jobs:
         uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
         id: versions
         with:
-          path: third_party/astroglobe
+          path: third_party/astrolabe
           fallbackNode: '^20'
           fallbackNpm: '^10'
 
@@ -137,7 +137,7 @@ jobs:
     name: Stylelint
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -146,7 +146,7 @@ jobs:
         uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
         id: versions
         with:
-          path: third_party/astroglobe
+          path: third_party/astrolabe
           fallbackNode: '^20'
           fallbackNpm: '^10'
 
@@ -175,7 +175,7 @@ jobs:
     name: PHP CS Fixer
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -184,7 +184,7 @@ jobs:
         id: versions
         uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
         with:
-          filename: third_party/astroglobe/appinfo/info.xml
+          filename: third_party/astrolabe/appinfo/info.xml
 
       - name: Set up php${{ steps.versions.outputs.php-min }}
         uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
@@ -212,7 +212,7 @@ jobs:
     name: Psalm
     defaults:
       run:
-        working-directory: third_party/astroglobe
+        working-directory: third_party/astrolabe
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -221,7 +221,7 @@ jobs:
         id: versions
         uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
         with:
-          filename: third_party/astroglobe/appinfo/info.xml
+          filename: third_party/astrolabe/appinfo/info.xml
 
       - name: Set up php${{ steps.versions.outputs.php-min }}
         uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
@@ -242,7 +242,7 @@ jobs:
         id: ocp-versions
         uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.3.1
         with:
-          filename: third_party/astroglobe/appinfo/info.xml
+          filename: third_party/astrolabe/appinfo/info.xml
 
       - name: Install OCP for static analysis
         run: |
@@ -253,14 +253,62 @@ jobs:
       - name: Run Psalm
         run: composer run psalm -- --threads=1 --monochrome --no-progress --output-format=github
 
+  # PHPUnit Tests
+  phpunit:
+    runs-on: ubuntu-latest
+    needs: changes
+    if: needs.changes.outputs.php != 'false'
+    defaults:
+      run:
+        working-directory: third_party/astrolabe
+
+    strategy:
+      matrix:
+        php-versions: ['8.1', '8.2', '8.3']
+
+    name: PHPUnit (PHP ${{ matrix.php-versions }})
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Set up PHP ${{ matrix.php-versions }}
+        uses: shivammathur/setup-php@cf4cade2721270509d5b1c766ab3549210a39a2a # v2.33.0
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: ctype, curl, dom, gd, iconv, intl, json, mbstring, openssl, posix, sqlite, xml, zip
+          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/astrolabe/appinfo/info.xml
+
+      - name: Install OCP for testing
+        run: |
+          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 PHPUnit
+        run: composer run test:unit
+
   # Summary job
   summary:
     permissions:
       contents: none
     runs-on: ubuntu-latest
-    needs: [changes, node-build, eslint, stylelint, php-cs, psalm]
+    needs: [changes, node-build, eslint, stylelint, php-cs, psalm, phpunit]
     if: always()
-    name: astroglobe-ci-summary
+    name: astrolabe-ci-summary
     steps:
       - name: Summary status
         run: |
@@ -268,7 +316,7 @@ jobs:
             echo "Frontend checks failed"
             exit 1
           fi
-          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success') }}; then
+          if ${{ needs.changes.outputs.php != 'false' && (needs.php-cs.result != 'success' || needs.psalm.result != 'success' || needs.phpunit.result != 'success') }}; then
             echo "PHP checks failed"
             exit 1
           fi

.github/workflows/bump-version.yml

@@ -21,9 +21,9 @@ jobs:
           token: "${{ secrets.PERSONAL_ACCESS_TOKEN }}"
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
-          python-version: '3.14'
+          python-version: '3.11'
 
       - name: Install uv
         run: |
@@ -87,21 +87,32 @@ jobs:
           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)
 
+          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..."
+            HELM_HAS_COMMITS=true
+          fi
+
+          if [ "$HELM_HAS_COMMITS" = true ]; then
+            echo "Bumping Helm chart version (helm-scoped commits)..."
             ./scripts/bump-helm.sh
             BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
+          elif [ "$MCP_BUMPED" = true ]; then
+            echo "Bumping Helm chart version (appVersion changed)..."
+            ./scripts/bump-helm.sh --increment PATCH
+            BUMPED_COMPONENTS="$BUMPED_COMPONENTS helm"
           fi
 
           # Bump Astrolabe (scope: astrolabe)
@@ -130,29 +141,36 @@ jobs:
           echo "Pushed tags for components:${{ steps.bump.outputs.components }}"
 
       - name: Summary
-        if: steps.bump.outputs.bumped == 'true'
         run: |
-          echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "The following components were bumped:" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ steps.bump.outputs.bumped }}" == "true" ]; then
+            echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The following components were bumped:" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
 
-          for component in ${{ steps.bump.outputs.components }}; do
-            case $component in
-              mcp)
-                tag=$(git tag --sort=-creatordate | grep -E '^v[0-9]' | head -n 1)
-                echo "- **MCP Server**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
-                ;;
-              helm)
-                tag=$(git tag --sort=-creatordate | grep -E '^nextcloud-mcp-server-' | head -n 1)
-                echo "- **Helm Chart**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
-                ;;
-              astrolabe)
-                tag=$(git tag --sort=-creatordate | grep -E '^astrolabe-v' | head -n 1)
-                echo "- **Astrolabe**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
-                ;;
-            esac
-          done
+            for component in ${{ steps.bump.outputs.components }}; do
+              case $component in
+                mcp)
+                  tag=$(git tag --sort=-creatordate | grep -E '^v[0-9]' | head -n 1)
+                  echo "- **MCP Server**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+                helm)
+                  tag=$(git tag --sort=-creatordate | grep -E '^nextcloud-mcp-server-' | head -n 1)
+                  echo "- **Helm Chart**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+                astrolabe)
+                  tag=$(git tag --sort=-creatordate | grep -E '^astrolabe-v' | head -n 1)
+                  echo "- **Astrolabe**: \`$tag\`" >> $GITHUB_STEP_SUMMARY
+                  ;;
+              esac
+            done
 
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "Tags have been pushed and release workflows will trigger automatically." >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Tags have been pushed and release workflows will trigger automatically." >> $GITHUB_STEP_SUMMARY
+          else
+            echo "## Version Bump Summary" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "✅ No version bumps required - no relevant commits found since last release." >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "The workflow completed successfully with no changes." >> $GITHUB_STEP_SUMMARY
+          fi

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

@@ -33,9 +33,10 @@ jobs:
 
       - name: Run Claude Code Review
         id: claude-review
-        uses: anthropics/claude-code-action@d7b6d50442a89f005016e778bf825a72ef582525 # v1
+        uses: anthropics/claude-code-action@b113f49a56229d8276e2bf05743ad6900121239c # v1.0.45
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          allowed_bots: "renovate-bot-cbcoutinho"
           prompt: |
             REPO: ${{ github.repository }}
             PR NUMBER: ${{ github.event.pull_request.number }}

.github/workflows/claude.yml

@@ -32,7 +32,7 @@ jobs:
 
       - name: Run Claude Code
         id: claude
-        uses: anthropics/claude-code-action@d7b6d50442a89f005016e778bf825a72ef582525 # v1
+        uses: anthropics/claude-code-action@b113f49a56229d8276e2bf05743ad6900121239c # v1.0.45
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 

.github/workflows/helm-release.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - v*
+      - nextcloud-mcp-server-*
 
 jobs:
   release:

.github/workflows/rag-evaluation.yml

@@ -27,7 +27,7 @@ jobs:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - 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@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
 
       - name: Wait for Nextcloud to be ready
         run: |

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
       - name: Install uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
       - name: Install Python 3.11
         run: uv python install 3.11
       - name: Build

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@681c641aba71e4a1c380be3ab5e12ad51f415867 # v7.1.6
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -48,15 +48,32 @@ 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@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
 
       - name: Install Playwright dependencies
         run: |

CHANGELOG.md

@@ -5,6 +5,195 @@ All notable changes to the Nextcloud MCP Server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://peps.python.org/pep-0440/).
 
+## v0.63.1 (2026-02-03)
+
+### Fix
+
+- **helm**: add backward compatibility for legacy persistence configs
+
+## v0.63.0 (2026-01-28)
+
+### Feat
+
+- **astrolabe**: add background token refresh job
+
+### Fix
+
+- **astrolabe**: add pagination and psalm fixes for token refresh
+- **astrolabe**: add locking to prevent token refresh race condition
+- **astrolabe**: add issued_at to on-demand token refresh
+
+## v0.62.0 (2026-01-26)
+
+### Feat
+
+- **scripts**: add database query helpers for development
+
+### Fix
+
+- **astrolabe**: resolve Psalm type errors in PDF preview code
+- **astrolabe**: fix Psalm baseline and ESLint import order
+- **astrolabe**: load pdfjs-dist externally to fix PDF viewer
+- **astrolabe**: improve error messages for authorization issues
+- **astrolabe**: rename OAuthController and fix app password check
+- **tests**: improve Astrolabe integration test reliability
+- **astrolabe**: update Plotly title attributes for v3 compatibility
+- **deps**: update dependency plotly.js-dist-min to v3
+
+### Refactor
+
+- **api**: split management.py into domain-focused modules
+- **astrolabe**: replace client-side PDF.js with server-side PyMuPDF rendering
+
+## v0.61.5 (2026-01-17)
+
+### Fix
+
+- **astrolabe**: improve token refresh error handling and validation
+- **astrolabe**: delete stale tokens when refresh fails
+- **astrolabe**: resolve CI failures for code quality checks
+- **astrolabe**: use internal URL for OAuth token refresh
+
+### Refactor
+
+- **astrolabe**: add PHP property types to fix Psalm errors
+- **astrolabe**: upgrade to @nextcloud/vue 9.3.3 API
+
+## v0.61.4 (2026-01-16)
+
+### Fix
+
+- **astrolabe**: Address reviewer feedback for hybrid mode
+- **astrolabe**: Fix NcSelect options and CSS loading
+- **astrolabe**: fix OAuth flow and settings UI for hybrid mode
+- **api**: return OIDC config in hybrid mode for Astrolabe OAuth flow
+
+## v0.61.3 (2026-01-15)
+
+### Fix
+
+- **astrolabe**: address review feedback for Vue 3 bindings
+- **astrolabe**: update Vue component bindings for Vue 3 compatibility
+
+## v0.61.2 (2026-01-15)
+
+### Fix
+
+- **ci**: bump helm chart version when MCP appVersion changes
+
+## v0.61.1 (2026-01-15)
+
+### Fix
+
+- **astrolabe**: define appName and appVersion for @nextcloud/vue
+
+## v0.61.0 (2026-01-14)
+
+### Feat
+
+- Add rate limiting and extract helpers for app password endpoints
+
+### Fix
+
+- Add missing annotations for deck remove/unassign operations
+- **auth**: Store app passwords locally for multi-user BasicAuth background sync
+
+### Refactor
+
+- Use get_settings() for vector sync enabled check
+- Extract storage helper and improve PHP error handling
+
+## v0.60.4 (2026-01-12)
+
+### Fix
+
+- **deck**: use correct endpoint for reorder_card to fix cross-stack moves
+
+## v0.60.3 (2025-12-31)
+
+### Fix
+
+- **deck**: Always preserve fields in update_card for partial updates
+- **astrolabe**: Fix CSS loading for Nextcloud apps
+- **astrolabe**: Fix revoke access button HTTP method mismatch
+
+## v0.60.2 (2025-12-29)
+
+### Fix
+
+- **oauth**: Enable browser OAuth routes for Management API in hybrid mode
+
+## v0.60.1 (2025-12-26)
+
+### Fix
+
+- **mcp**: Move all imports to the top of modules
+
+## v0.60.0 (2025-12-26)
+
+### Feat
+
+- Remove URL rewriting in favor of proper nextcloud config
+- **helm**: migrate to new environment variable naming convention
+- Migrate to vue 3
+- **astrolabe**: upgrade to Vue 3 and @nextcloud/vue 9
+
+### Fix
+
+- **tests**: Add singleton reset fixture to prevent anyio.WouldBlock errors
+- **tests**: Fix integration test failures in qdrant, sampling, and rag tests
+- **auth**: Skip issuer validation for management API tokens
+- Use settings.enable_offline_access for env var consolidation
+- Add required config.py attributes
+- **docker**: remove overwritehost to fix container-to-container DCR
+- **deps**: update dependency @nextcloud/vue to v9
+- **deps**: update dependency vue to v3
+
+### Refactor
+
+- **auth**: Decouple BasicAuth and OAuth authentication strategies
+
+## v0.59.1 (2025-12-22)
+
+### Fix
+
+- **helm**: set OIDC client env vars when using existingSecret
+- **helm**: trigger chart release workflow on helm chart tags
+
+## v0.59.0 (2025-12-22)
+
+### Feat
+
+- **helm**: add support for multi-user BasicAuth mode
+
+### Fix
+
+- **helm**: address PR #447 reviewer feedback
+- **helm**: include MCP server version bumps in changelog pattern
+
+## v0.58.0 (2025-12-22)
+
+### Feat
+
+- **config**: enable DCR for multi-user BasicAuth with offline access
+- **astrolabe**: implement app password provisioning for multi-user background sync
+- **config**: consolidate configuration with smart dependency resolution (ADR-021)
+
+## v0.57.0 (2025-12-20)
+
+### Feat
+
+- **auth**: add multi-user BasicAuth pass-through mode
+- **astrolabe**: add dynamic MCP server configuration for testing
+
+### Fix
+
+- **config**: address reviewer feedback
+
+### Refactor
+
+- **config**: centralize configuration validation and simplify startup
+
 ## v0.56.2 (2025-12-20)
 
 ### Fix

CLAUDE.md

@@ -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:**

Dockerfile

@@ -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:43e4d702bbfe3bd6d5b743dc571b67c19121302eb172951a9b7b0149783a1c21
 
-COPY --from=ghcr.io/astral-sh/uv:0.9.18@sha256:5713fa8217f92b80223bc83aac7db36ec80a84437dbc0d04bbc659cae030d8c9 /uv /uvx /bin/
+COPY --from=ghcr.io/astral-sh/uv:0.10.0@sha256:78a7ff97cd27b7124a5f3c2aefe146170793c56a1e03321dd31a289f6d82a04f /uv /uvx /bin/
 
 # Install dependencies
 # 1. git (required for caldav dependency from git)

Dockerfile.smithery

@@ -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:43e4d702bbfe3bd6d5b743dc571b67c19121302eb172951a9b7b0149783a1c21
 
 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.0@sha256:78a7ff97cd27b7124a5f3c2aefe146170793c56a1e03321dd31a289f6d82a04f /uv /uvx /bin/
 
 # Install dependencies
 # 1. git (required for caldav dependency from git)

README.md

@@ -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
@@ -127,7 +133,7 @@ This enables natural language queries and helps discover related content across
 
 > [!NOTE]
 > **Semantic Search is experimental and opt-in:**
-> - Disabled by default (`VECTOR_SYNC_ENABLED=false`)
+> - Disabled by default (`ENABLE_SEMANTIC_SEARCH=false`)
 > - Currently supports Notes app only (multi-app support planned)
 > - Requires additional infrastructure: vector database + embedding service
 > - Answer generation (`nc_semantic_search_answer`) requires MCP client sampling support

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

@@ -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"

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

@@ -2,7 +2,7 @@
 
 set -euox pipefail
 
-echo "Installing and configuring Astrolabe app for testing..."
+echo "Installing Astrolabe app for testing..."
 
 # Check if development astrolabe app is mounted at /opt/apps/astrolabe
 if [ -d /opt/apps/astrolabe ]; then
@@ -30,55 +30,7 @@ else
     php /var/www/html/occ app:enable astrolabe
 fi
 
-# Configure MCP server URLs in Nextcloud system config
-# - mcp_server_url: Internal URL for PHP app to call MCP server APIs (Docker internal network)
-# - mcp_server_public_url: Public URL for OAuth token audience (what browsers/MCP clients see)
-php /var/www/html/occ config:system:set mcp_server_url --value='http://mcp-oauth:8001'
-php /var/www/html/occ config:system:set mcp_server_public_url --value='http://localhost:8001'
-
-# Create OAuth client for Astrolabe app
-# The resource_url MUST match what the MCP server expects as token audience
-# This allows tokens from this client to be validated by MCP server's UnifiedTokenVerifier
-MCP_CLIENT_ID="nextcloudMcpServerUIPublicClient"
-MCP_RESOURCE_URL="http://localhost:8001"
-MCP_REDIRECT_URI="http://localhost:8080/apps/astrolabe/oauth/callback"
-
-echo "Configuring OAuth client for Astrolabe..."
-
-# Check if client already exists
-if php /var/www/html/occ oidc:list 2>/dev/null | grep -q "$MCP_CLIENT_ID"; then
-    echo "OAuth client $MCP_CLIENT_ID already exists, removing to recreate with correct settings..."
-    php /var/www/html/occ oidc:remove "$MCP_CLIENT_ID" || true
-fi
-
-# Create OAuth client with correct resource_url for MCP server audience
-echo "Creating OAuth confidential client with resource_url=$MCP_RESOURCE_URL"
-CLIENT_OUTPUT=$(php /var/www/html/occ oidc:create \
-    "Astrolabe" \
-    "$MCP_REDIRECT_URI" \
-    --client_id="$MCP_CLIENT_ID" \
-    --type=confidential \
-    --flow=code \
-    --token_type=jwt \
-    --resource_url="$MCP_RESOURCE_URL" \
-    --allowed_scopes="openid profile email offline_access notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write")
-
-echo "$CLIENT_OUTPUT"
-
-# Extract client_secret from JSON output
-CLIENT_SECRET=$(echo "$CLIENT_OUTPUT" | php -r 'echo json_decode(file_get_contents("php://stdin"), true)["client_secret"] ?? "";')
-
-if [ -n "$CLIENT_SECRET" ]; then
-    echo "Configuring Astrolabe client secret in system config..."
-    php /var/www/html/occ config:system:set astrolabe_client_secret --value="$CLIENT_SECRET"
-    echo "✓ Client secret configured: ${CLIENT_SECRET:0:8}..."
-else
-    echo "⚠ Warning: Could not extract client_secret from OIDC client creation"
-fi
-
-# Configure OAuth client ID in system config
-echo "Configuring Astrolabe client ID in system config..."
-php /var/www/html/occ config:system:set astrolabe_client_id --value="$MCP_CLIENT_ID"
-echo "✓ Client ID configured: $MCP_CLIENT_ID"
-
-echo "Astrolabe app installed and configured 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."

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

@@ -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"

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

@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.54.0"
+version = "0.57.37"
 tag_format = "nextcloud-mcp-server-$version"
 version_scheme = "semver"
 update_changelog_on_bump = true
@@ -18,7 +18,8 @@ ignored_tag_formats = [
 ]
 
 # Filter commits by scope
+# Includes helm-scoped commits AND MCP server version bumps (which update appVersion)
 [tool.commitizen.customize]
-changelog_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:"
+changelog_pattern = "^((feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:|bump: version.*→.*)"
 schema_pattern = "^(feat|fix|docs|refactor|perf|test|build|ci|chore)\\(helm\\)(!)?:\\s.+"
 message_template = "{{change_type}}(helm): {{message}}"

charts/nextcloud-mcp-server/CHANGELOG.md

@@ -14,6 +14,250 @@ 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.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

charts/nextcloud-mcp-server/Chart.lock

@@ -1,9 +1,9 @@
 dependencies:
 - name: qdrant
   repository: https://qdrant.github.io/qdrant-helm
-  version: 1.16.2
+  version: 1.16.3
 - name: ollama
   repository: https://otwld.github.io/ollama-helm
-  version: 1.36.0
-digest: sha256:fab8008217b27ff4e3e139c2f481eedaa23f9f64a3a086d0e9deea2195b69b63
-generated: "2025-12-14T11:07:07.024787592Z"
+  version: 1.41.0
+digest: sha256:1d5b958a64eb2102cf347ec199638bfac5b289bafdecff2529099ee6bce03b86
+generated: "2026-02-04T11:09:21.837825534Z"

charts/nextcloud-mcp-server/Chart.yaml

@@ -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.56.2"
+version: 0.57.37
+appVersion: "0.63.1"
 keywords:
   - nextcloud
   - mcp
@@ -27,10 +27,10 @@ annotations:
   grafana_dashboard_folder: "Nextcloud MCP"
 dependencies:
   - name: qdrant
-    version: "1.16.2"
+    version: "1.16.3"
     repository: https://qdrant.github.io/qdrant-helm
     condition: qdrant.networkMode.deploySubchart
   - name: ollama
-    version: "1.36.0"
+    version: "1.41.0"
     repository: https://otwld.github.io/ollama-helm
     condition: ollama.enabled

charts/nextcloud-mcp-server/README.md

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

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

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

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

@@ -72,6 +72,28 @@ Create the name of the secret to use for basic auth
 {{- end }}
 {{- end }}
 
+{{/*
+Create the name of the secret to use for multi-user basic auth
+*/}}
+{{- define "nextcloud-mcp-server.multiUserBasicSecretName" -}}
+{{- if .Values.auth.multiUserBasic.existingSecret }}
+{{- .Values.auth.multiUserBasic.existingSecret }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-multi-user-basic
+{{- end }}
+{{- end }}
+
+{{/*
+Create the name of the PVC to use for multi-user basic token storage
+*/}}
+{{- define "nextcloud-mcp-server.multiUserBasicPvcName" -}}
+{{- if .Values.auth.multiUserBasic.persistence.existingClaim }}
+{{- .Values.auth.multiUserBasic.persistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-token-storage
+{{- end }}
+{{- end }}
+
 {{/*
 Create the name of the secret to use for OAuth
 */}}
@@ -105,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
 */}}

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

@@ -68,7 +68,7 @@ spec:
             - name: NEXTCLOUD_HOST
               value: {{ .Values.nextcloud.host | quote }}
             {{- if eq .Values.auth.mode "basic" }}
-            # Basic auth mode
+            # Basic auth mode (single-user)
             - name: NEXTCLOUD_USERNAME
               valueFrom:
                 secretKeyRef:
@@ -79,6 +79,41 @@ spec:
                 secretKeyRef:
                   name: {{ include "nextcloud-mcp-server.basicAuthSecretName" . }}
                   key: {{ .Values.auth.basic.passwordKey }}
+            {{- else if eq .Values.auth.mode "multi-user-basic" }}
+            # Multi-user BasicAuth mode (pass-through)
+            - name: ENABLE_MULTI_USER_BASIC_AUTH
+              value: "true"
+            - name: NEXTCLOUD_MCP_SERVER_URL
+              value: {{ include "nextcloud-mcp-server.mcpServerUrl" . | quote }}
+            - name: NEXTCLOUD_PUBLIC_ISSUER_URL
+              value: {{ include "nextcloud-mcp-server.publicIssuerUrl" . | quote }}
+            {{- if .Values.auth.multiUserBasic.enableOfflineAccess }}
+            # Background operations with app passwords (replaces deprecated ENABLE_OFFLINE_ACCESS)
+            - name: ENABLE_BACKGROUND_OPERATIONS
+              value: "true"
+            - name: TOKEN_STORAGE_DB
+              value: {{ .Values.auth.multiUserBasic.tokenStorageDb | quote }}
+            - name: TOKEN_ENCRYPTION_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.tokenEncryptionKeyKey }}
+            - name: NEXTCLOUD_OIDC_SCOPES
+              value: {{ .Values.auth.multiUserBasic.scopes | quote }}
+            {{- if or .Values.auth.multiUserBasic.clientId .Values.auth.multiUserBasic.existingSecret }}
+            # Static OAuth credentials (optional - uses DCR if not provided)
+            - name: NEXTCLOUD_OIDC_CLIENT_ID
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.clientIdKey }}
+            - name: NEXTCLOUD_OIDC_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "nextcloud-mcp-server.multiUserBasicSecretName" . }}
+                  key: {{ .Values.auth.multiUserBasic.clientSecretKey }}
+            {{- end }}
+            {{- end }}
             {{- else if eq .Values.auth.mode "oauth" }}
             # OAuth mode
             - name: NEXTCLOUD_MCP_SERVER_URL
@@ -87,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:
@@ -147,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
@@ -251,10 +286,8 @@ spec:
             - name: oauth-storage
               mountPath: /app/.oauth
             {{- end }}
-            {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
-            - name: qdrant-data
+            - name: data-storage
               mountPath: /app/data
-            {{- end }}
             {{- with .Values.volumeMounts }}
             {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -266,10 +299,12 @@ spec:
           persistentVolumeClaim:
             claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
         {{- end }}
-        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
-        - name: qdrant-data
+        - name: data-storage
+        {{- if eq (include "nextcloud-mcp-server.dataStorageEnabled" .) "true" }}
           persistentVolumeClaim:
-            claimName: {{ include "nextcloud-mcp-server.qdrantPvcName" . }}
+            claimName: {{ include "nextcloud-mcp-server.dataStoragePvcName" . }}
+        {{- else }}
+          emptyDir: {}
         {{- end }}
         {{- with .Values.volumes }}
         {{- toYaml . | nindent 8 }}

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

@@ -16,20 +16,34 @@ spec:
       storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
 ---
-{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.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" . }}-qdrant-data
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-data-storage
   labels:
     {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
 spec:
   accessModes:
-    - {{ .Values.qdrant.localPersistence.accessMode }}
-  {{- if .Values.qdrant.localPersistence.storageClass }}
-  storageClassName: {{ .Values.qdrant.localPersistence.storageClass }}
+    - {{ $accessMode }}
+  {{- if $storageClass }}
+  storageClassName: {{ $storageClass }}
   {{- end }}
   resources:
     requests:
-      storage: {{ .Values.qdrant.localPersistence.size }}
+      storage: {{ $size }}
 {{- end }}

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

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

charts/nextcloud-mcp-server/values.yaml

@@ -26,21 +26,29 @@ 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: ""
 
 # Authentication configuration
-# Choose either basic auth OR oauth (not both)
+# Choose one mode: "basic", "multi-user-basic", or "oauth"
 auth:
-  # Authentication mode: "basic" or "oauth"
-  # basic: Uses username/password (recommended for most users)
+  # Authentication mode: "basic", "multi-user-basic", or "oauth"
+  # basic: Single-user with username/password (recommended for personal use)
+  # multi-user-basic: Multi-user with BasicAuth pass-through (credentials in request headers)
   # oauth: Uses OAuth2/OIDC (experimental, requires patches)
   mode: basic
 
-  # Basic authentication settings
+  # Basic authentication settings (single-user mode)
   basic:
     # Nextcloud username (ignored if existingSecret is set)
     username: ""
@@ -58,6 +66,47 @@ auth:
     usernameKey: "username"
     passwordKey: "password"
 
+  # Multi-user BasicAuth settings (pass-through mode)
+  # Users provide credentials in request headers (Authorization: Basic ...)
+  # Server optionally stores app passwords for background operations
+  multiUserBasic:
+    # Enable offline access (background operations using app passwords via Astrolabe)
+    # When enabled, requires token encryption key. OAuth client credentials are optional (uses DCR if not provided)
+    enableOfflineAccess: false
+    # Token encryption key (required if enableOfflineAccess: true, ignored if existingSecret is set)
+    # Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+    tokenEncryptionKey: ""
+    # Token storage database path
+    tokenStorageDb: "/app/data/tokens.db"
+    # OAuth client credentials (optional - uses Dynamic Client Registration if not provided)
+    # Only needed if enableOfflineAccess: true
+    clientId: ""
+    clientSecret: ""
+    # OAuth scopes to request (space-separated)
+    scopes: "openid profile email offline_access notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write todo:read todo:write"
+    # Use existing secret for multi-user basic auth credentials
+    # If set, tokenEncryptionKey, clientId, and clientSecret above are ignored
+    # Secret should contain keys specified in the *Key fields below
+    # Example:
+    #   kubectl create secret generic my-multiuser-creds \
+    #     --from-literal=token_encryption_key=ESF1BvEQ... \
+    #     --from-literal=client_id=my-client-id \
+    #     --from-literal=client_secret=my-client-secret
+    existingSecret: ""
+    # Keys in the existing secret
+    tokenEncryptionKeyKey: "token_encryption_key"
+    clientIdKey: "client_id"
+    clientSecretKey: "client_secret"
+    # Persistent storage for token database
+    persistence:
+      enabled: true
+      # Storage class (leave empty for default)
+      storageClass: ""
+      accessMode: ReadWriteOnce
+      size: 100Mi
+      # Use existing PVC
+      existingClaim: ""
+
   # OAuth2/OIDC settings (experimental)
   oauth:
     # OAuth token type: "jwt" or "opaque"
@@ -90,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)
@@ -316,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
@@ -330,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

docker-compose.yml

@@ -3,11 +3,13 @@ services:
   # https://hub.docker.com/_/mariadb
   db:
     # Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
-    image: docker.io/library/mariadb:lts@sha256:1cac8492bd78b1ec693238dc600be173397efd7b55eabc725abc281dc855b482
+    image: docker.io/library/mariadb:lts@sha256:345fa26d595e8c7fe298e0c4098ed400356f502458769c8902229b3437d6da2b
     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:0804c395e634e624243387d3c3a9c45fcaca876d313c2c8b52c3fdf9a912dded
     restart: always
 
   app:
-    image: docker.io/library/nextcloud:32.0.3@sha256:53231a9fb9233af2c15bfe70fc03ebe639fd53243fa42a9369884b1e0008deae
+    image: docker.io/library/nextcloud:32.0.5@sha256:4b66e9bd8cb2c8af5457c1e2606c9937af2fcccbe4f6338956bc5990caec8968
     restart: always
     ports:
-      - 0.0.0.0:8080:80
+      - 127.0.0.1:8080:80
     depends_on:
       - redis
       - db
@@ -35,7 +37,7 @@ 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
+      - ./third_party/astrolabe:/opt/apps/astrolabe:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -52,14 +54,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:9945a842ba983afcf110053cbcc0df7e4bd09ba9f02aa213824ce3f986713635
     restart: always
     ports:
       - 127.0.0.1:8002:8000
@@ -86,8 +88,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
 
@@ -123,6 +125,40 @@ services:
       # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
       # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
 
+  mcp-multi-user-basic:
+    build: .
+    restart: always
+    command: ["--transport", "streamable-http"]
+    depends_on:
+      app:
+        condition: service_healthy
+    ports:
+      - 127.0.0.1:8003:8000
+    environment:
+      # Multi-user BasicAuth pass-through mode (ADR-020)
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8003
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+      - ENABLE_MULTI_USER_BASIC_AUTH=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
+
+      # Token storage (required for middleware initialization)
+      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      - ENABLE_SEMANTIC_SEARCH=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      # OAuth credentials for background sync (optional - uses DCR if not provided)
+      # Uncomment to avoid DCR:
+      # - NEXTCLOUD_OIDC_CLIENT_ID=your_client_id
+      # - NEXTCLOUD_OIDC_CLIENT_SECRET=your_client_secret
+
+      # NO admin credentials - credentials come from client Authorization header
+    volumes:
+      - multi-user-basic-data:/app/data
+
   mcp-oauth:
     build: .
     command: ["--transport", "streamable-http", "--oauth", "--port", "8001", "--oauth-token-type", "jwt"]
@@ -143,7 +179,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
 
@@ -151,14 +187,19 @@ 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
 
       # Qdrant configuration - persistent local storage
       - QDRANT_LOCATION=/app/data/qdrant
 
+      # Embedding provider for vector sync (use Simple provider as fallback)
+      # Ollama not available in CI/test environments
+      # - OLLAMA_BASE_URL=http://ollama:11434
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
       # NO admin credentials - using OAuth with Dynamic Client Registration (DCR)
       # Client credentials registered via RFC 7591 and stored in volume
       # JWT token type is used for testing (faster validation, scopes embedded in token)
@@ -167,7 +208,7 @@ services:
       - oauth-tokens:/app/data
 
   keycloak:
-    image: quay.io/keycloak/keycloak:26.4.7@sha256:9409c59bdfb65dbffa20b11e6f18b8abb9281d480c7ca402f51ed3d5977e6007
+    image: quay.io/keycloak/keycloak:26.5.1@sha256:b80a48090594367bd8cf6fe2019466ac4ea49de4d0830fb2a43256eda37b18f5
     command:
       - "start-dev"
       - "--import-realm"
@@ -215,7 +256,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
 
@@ -248,13 +289,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
@@ -280,3 +321,4 @@ volumes:
   keycloak-oauth-storage:
   qdrant-data:
   mcp-data:
+  multi-user-basic-data:

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

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

docs/ADR-021-configuration-consolidation.md

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

docs/auth-flows.md

@@ -0,0 +1,461 @@
+# 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.
+
+---
+
+## Astrolabe Background Token Refresh
+
+The Astrolabe Nextcloud app includes a background job that proactively refreshes OAuth tokens before expiration.
+
+```
+Nextcloud Cron                Astrolabe                    MCP Server IdP
+    │                             │                            │
+    │── Run RefreshUserTokens ───▶│                            │
+    │   (every 15 minutes)        │                            │
+    │                             │── Get all user tokens ────▶│
+    │                             │   (from preferences)       │
+    │                             │                            │
+    │   [For each user]           │                            │
+    │                             │── Check expiry ───────────▶│
+    │                             │   refresh if <50% lifetime │
+    │                             │                            │
+    │                             │── Acquire user lock ──────▶│
+    │                             │   (prevent race condition) │
+    │                             │                            │
+    │                             │── Token refresh request ──▶│
+    │                             │   grant_type=refresh_token │
+    │                             │◀── New tokens ─────────────│
+    │                             │                            │
+    │                             │── Store new tokens ───────▶│
+    │                             │   (with issued_at)         │
+    │◀── Job complete ────────────│                            │
+```
+
+**Key characteristics:**
+- Runs every 15 minutes via Nextcloud cron
+- Refreshes when <50% of token lifetime remains
+- Uses locking to prevent race conditions with on-demand refresh
+- Stores `issued_at` timestamp for accurate lifetime calculation
+- Batch processing (100 users at a time) for memory efficiency
+
+**Implementation:** `third_party/astrolabe/lib/BackgroundJob/RefreshUserTokens.php`
+
+---
+
+## Configuration Quick Reference
+
+### Single-User BasicAuth
+```bash
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+```
+
+### Multi-User BasicAuth
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_MULTI_USER_BASIC_AUTH=true
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### OAuth Single-Audience (Default)
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+# No username/password triggers OAuth mode
+
+# Optional: Static client credentials (instead of DCR)
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### OAuth Token Exchange
+```bash
+NEXTCLOUD_HOST=http://nextcloud.example.com
+ENABLE_TOKEN_EXCHANGE=true
+NEXTCLOUD_OIDC_CLIENT_ID=<client-id>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>
+
+# Optional: For background sync
+ENABLE_OFFLINE_ACCESS=true
+TOKEN_ENCRYPTION_KEY=<32-byte-key>
+TOKEN_STORAGE_DB=/data/tokens.db
+```
+
+### Smithery Stateless
+```bash
+SMITHERY_DEPLOYMENT=true
+# All other config comes from session URL parameters
+```
+
+---
+
+## Related Documentation
+
+- [Authentication](authentication.md) - Configuration details and setup guides
+- [OAuth Architecture](oauth-architecture.md) - Deep OAuth protocol details
+- [ADR-004: Progressive Consent](ADR-004-mcp-application-oauth.md) - Dual OAuth flow architecture
+- [ADR-005: Token Audience Validation](ADR-005-token-audience-validation.md) - Audience validation strategy
+- [ADR-018: Nextcloud PHP App](ADR-018-nextcloud-php-app-for-settings-ui.md) - Astrolabe integration
+- [ADR-020: Deployment Modes](ADR-020-deployment-modes-and-configuration-validation.md) - Mode detection and validation

docs/authentication.md

@@ -140,6 +140,142 @@ 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)
+
+When Astrolabe connects to an MCP server running in hybrid mode, users must complete a **two-step credential setup**:
+
+#### Step 1: OAuth Authorization (Search Access)
+
+**Purpose**: Allows Astrolabe to call MCP server APIs on the user's behalf.
+
+**Flow**:
+1. User opens Astrolabe Personal Settings in Nextcloud
+2. Clicks "Authorize" button
+3. Redirected to Astrolabe's OAuth controller (`/apps/astrolabe/oauth/initiate`)
+4. OAuth controller discovers IdP from MCP server's `/api/v1/status` endpoint
+5. User authenticates with Identity Provider (Nextcloud OIDC or external IdP)
+6. Tokens stored in Nextcloud user config (`McpTokenStorage`)
+7. Astrolabe can now perform semantic searches via MCP API
+
+**Technical Details**:
+- Token audience: MCP server
+- Token storage: Nextcloud app config (`oc_preferences`)
+- Used for: `/api/v1/search`, `/api/v1/status` (authenticated endpoints)
+
+#### Step 2: App Password (Background Indexing)
+
+**Purpose**: Allows MCP server to access Nextcloud content for background sync.
+
+**Flow**:
+1. User generates app password in Nextcloud Security settings
+2. Enters app password in Astrolabe Personal Settings
+3. App password validated against Nextcloud and stored (encrypted)
+4. MCP server can now index user's content in the background
+
+**Technical Details**:
+- Credential type: Nextcloud app password
+- Token storage: MCP server's refresh token database
+- Used for: Background indexing, content sync to vector database
+
+#### Why Two Credentials?
+
+| Direction | Auth Method | Purpose |
+|-----------|-------------|---------|
+| Astrolabe → MCP Server | OAuth Bearer Token | User searches, settings management |
+| MCP Server → Nextcloud | BasicAuth (App Password) | Background content indexing |
+
+The separation ensures:
+- **Security**: Each credential has limited scope
+- **Audit Trail**: OAuth tokens identify users; app passwords enable background ops
+- **User Control**: Users explicitly grant each type of access
+
+### See Also
+- [OAuth Architecture](oauth-architecture.md) - Progressive Consent (Flow 2) details
+- [Configuration](configuration.md#enable_offline_access) - Hybrid mode configuration
+
 ## Mode Detection
 
 The server automatically detects the authentication mode:

docs/blog-introducing-astrolabe.md

@@ -0,0 +1,206 @@
+# Introducing Astrolabe: Navigate Your Data Universe in Nextcloud
+
+Your Nextcloud instance holds years of notes, projects, recipes, contacts, and documents. But when you need to find something, you're stuck typing exact keywords and hoping for the best. Search "car repair" and miss that note titled "Vehicle maintenance tips." Search "meeting agenda" and overlook the calendar event called "Team sync." Traditional keyword search demands that you remember exactly how you wrote things down.
+
+What if your search could understand what you *mean*, not just what you type?
+
+Meet **Astrolabe**—a Nextcloud app that brings AI-powered semantic search to your self-hosted cloud. Named after the ancient navigational instrument that helped travelers chart courses by the stars, Astrolabe helps you navigate your personal knowledge by mapping the semantic connections between your documents.
+
+## The Astrolabe Metaphor
+
+The astrolabe was one of humanity's most elegant scientific instruments—an analog computer for solving problems related to time and the position of celestial bodies. Its theoretical foundation traces back to **Hipparchus of Nicaea** (c. 190–120 BCE), who discovered the stereographic projection that allows a three-dimensional celestial sphere to be represented on a flat surface. Later Greek scholars like **Theon of Alexandria** and his daughter **Hypatia** refined it into a practical instrument, and during the Islamic Golden Age, astronomers in Baghdad, Damascus, and Cordoba perfected its design and applications.
+
+For nearly two millennia, astrolabes served astronomers, navigators, scholars, and religious officials across the Greek, Byzantine, Islamic, and medieval European worlds. These instruments allowed users to determine time, find celestial positions, calculate daylight hours, identify constellations, and even determine the direction of Mecca for prayer—all without complex calculations. The astrolabe made the vast complexity of the heavens understandable and navigable.
+
+**Astrolabe** (the app) does the same for your data. Every document, note, and calendar event becomes a point of light in your personal data universe. The app maps their semantic relationships—their meaning, not just their words—and suddenly the connections become visible. Documents cluster by topic, related ideas sit nearby, and you can navigate this landscape as naturally as medieval scholars once read the stars. Where the original astrolabe projected the celestial sphere onto brass, this one projects your knowledge into explorable semantic space.
+
+## Semantic Search: Find Meaning, Not Just Keywords
+
+The core feature of Astrolabe is semantic search. Instead of matching exact keywords, it understands the concepts in your query and finds related content.
+
+**What this looks like in practice:**
+
+| You Search For | Traditional Search Finds | Astrolabe Also Finds |
+|----------------|--------------------------|----------------------|
+| "car repair" | Documents containing "car repair" | Notes about "vehicle maintenance," "fixing the truck" |
+| "team planning" | Documents with "team planning" | Calendar events titled "Q2 kickoff," Deck cards about "project roadmap" |
+| "pasta recipes" | Documents with "pasta recipes" | Notes about "Italian cooking," "homemade noodles," "carbonara tips" |
+
+This works across multiple Nextcloud apps: Notes, Files (including PDFs with OCR), Deck cards, Calendar events, Contacts, and News/RSS items. One search bar, all your content, understood by meaning.
+
+### Hybrid Search: Best of Both Worlds
+
+Sometimes you want exact matches ("PROJ-2024-001"), sometimes you want semantic understanding ("that project from last year about authentication"). Astrolabe's hybrid search combines both approaches:
+
+- **Semantic search** uses embeddings to find conceptually related content
+- **BM25 keyword search** finds exact matches and important terms
+- **Reciprocal Rank Fusion (RRF)** intelligently merges the results
+
+You can adjust the balance or switch modes entirely depending on your needs.
+
+![Unified Search Integration](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/third_party/astrolabe/screenshots/01-unified-search-astrolabe.png?raw=1)
+*Astrolabe results appear alongside traditional search in Nextcloud's unified search bar*
+
+## Visualize Your Data Universe
+
+Beyond search, Astrolabe includes an interactive 3D visualization that shows your documents positioned in semantic space. Similar documents cluster together. Topics form constellations. You can rotate, zoom, and explore.
+
+This isn't just eye candy—it's a practical tool for knowledge discovery:
+
+- **Find forgotten connections**: Search for your current project and watch as related documents from months ago light up nearby
+- **Spot topic clusters**: See how your notes naturally group by subject
+- **Explore the unknown**: Click on points near your search results to discover content you didn't know was related
+
+The visualization uses Principal Component Analysis (PCA) to project high-dimensional embeddings (768 dimensions) down to 3D space while preserving the relationships between documents. We implemented a lightweight, custom PCA specifically for this—no heavyweight ML libraries required.
+
+![3D Vector Visualization](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/third_party/astrolabe/screenshots/02-semantic-search-with-plot.png?raw=1)
+*Documents cluster by semantic similarity. The query point (red) shows your search, and related documents cluster nearby*
+
+## Power Your AI Agents
+
+Astrolabe isn't just for humans—it's for your AI assistants too.
+
+The backend runs a **Model Context Protocol (MCP)** server, which means AI tools like Claude Desktop, Cursor, or custom agents can connect directly to your Nextcloud data. Your AI assistant can:
+
+- Search your notes semantically ("Find everything related to the Kubernetes migration")
+- Retrieve document content for context
+- Get AI-generated answers with citations from your documents (RAG)
+
+The critical point: **your data never leaves your infrastructure**. The MCP server runs on your hardware. Your AI assistant sends queries, the server returns results, and you maintain full control. No documents uploaded to third-party services.
+
+### Retrieval-Augmented Generation (RAG)
+
+Ask a question, and Astrolabe can retrieve relevant documents and have your AI synthesize an answer—complete with citations:
+
+```
+You: "What were the main issues we had deploying to production last month?"
+
+Astrolabe finds: 3 relevant notes, 2 Deck cards, 1 calendar event
+
+AI generates: "Based on your documents, there were three main issues:
+1. Database migration timeout (see Note: 'Prod deploy 2024-01-15')
+2. SSL certificate renewal (see Deck card: 'Ops Tasks')
+3. Resource limits on the new pods (see Note: 'K8s troubleshooting')
+```
+
+This uses MCP's sampling capability—the server doesn't run its own LLM. Instead, it asks your client's AI to generate the response. You choose the model, you control the costs.
+
+## Under the Hood
+
+For the technically curious, here's how Astrolabe works:
+
+### Embedding Providers
+
+Astrolabe supports multiple backends for generating semantic embeddings:
+
+- **Amazon Bedrock**: Enterprise-grade, Titan embeddings
+- **OpenAI**: Direct OpenAI API or compatible endpoints (including GitHub Models)
+- **Ollama**: Self-hosted, privacy-focused, runs entirely on your hardware
+
+The system auto-detects available providers based on environment variables and falls back gracefully. Deploy Ollama on your server for full privacy, or use Bedrock for enterprise scale—same codebase, zero code changes.
+
+### Background Indexing
+
+Documents are indexed automatically via webhooks. When you create or edit a note, Nextcloud fires an event, and the MCP server processes it in the background. No manual sync required.
+
+The indexing pipeline:
+1. **Scanner** detects changes via ETags and modification timestamps
+2. **Queue** manages backpressure (up to 10k pending documents)
+3. **Worker pool** processes embeddings concurrently (configurable, default 3 workers)
+4. **Qdrant** stores vectors for fast similarity search
+
+### Lightweight by Design
+
+We deliberately avoided heavyweight dependencies:
+
+- **Custom PCA**: No scikit-learn, just efficient eigendecomposition
+- **In-process async**: No separate message queues or worker processes—just anyio TaskGroups
+- **Plugin architecture**: New apps (Notes, Calendar, etc.) are simple scanner/processor implementations
+
+This means Astrolabe runs comfortably alongside your Nextcloud on modest hardware.
+
+```
+┌──────────────┐     ┌─────────────┐     ┌─────────┐
+│   Nextcloud  │────▶│ MCP Server  │────▶│ Qdrant  │
+│ (Astrolabe)  │◀────│  (Python)   │◀────│ (Vectors)│
+└──────────────┘     └─────────────┘     └─────────┘
+       │                    │
+       │ OAuth/Token        │ Embeddings
+       ▼                    ▼
+   ┌────────┐         ┌──────────┐
+   │  User  │         │ Ollama/  │
+   │Browser │         │ Bedrock  │
+   └────────┘         └──────────┘
+```
+
+## Getting Started
+
+### Requirements
+
+- Nextcloud 31 or 32
+- MCP server instance (Docker recommended)
+- Vector database (Qdrant, included in Docker setup)
+- Embedding provider (Ollama for self-hosted, or cloud options)
+
+### Quick Setup
+
+1. **Install the Astrolabe app** from the Nextcloud App Store (or manually)
+
+2. **Start the MCP server** (Docker Compose makes this easy):
+   ```bash
+   docker compose up -d mcp qdrant ollama
+   ```
+
+3. **Configure the connection** in your Nextcloud `config.php`:
+   ```php
+   'astrolabe' => [
+       'mcp_server_url' => 'http://localhost:8000',
+   ],
+   ```
+
+4. **Authorize access** in Settings → Personal → Astrolabe
+
+5. **Start searching** using Nextcloud's unified search bar
+
+For detailed setup instructions, including OAuth configuration and embedding provider options, see the [documentation](https://github.com/cbcoutinho/nextcloud-mcp-server).
+
+## What Can You Index?
+
+Astrolabe currently supports:
+
+| App | What Gets Indexed |
+|-----|-------------------|
+| **Notes** | Full text and metadata |
+| **Files** | PDFs (with OCR), DOCX, text files |
+| **Deck** | Card titles and descriptions |
+| **Calendar** | Event titles, descriptions, and details |
+| **Contacts** | Names, notes, and contact information |
+| **News** | RSS/Atom feed articles |
+
+Each result shows the document type, relevance score, and a direct link to the source. For large documents, it shows which chunk (section) matched.
+
+![Chunk Viewer](https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/third_party/astrolabe/screenshots/03-chunk-viewer-open.png?raw=1)
+*Click a result to see the matching chunk in context*
+
+## Who Is This For?
+
+**Researchers and students**: Find all notes related to your thesis topic, even when you used different terminology across semesters. Discover connections between papers you read months apart.
+
+**Teams and organizations**: Surface institutional knowledge that would otherwise stay buried. New team members can search for concepts instead of knowing exactly what to look for.
+
+**Developers**: Connect your AI coding assistant to your Nextcloud. Give it access to project notes, meeting records, and documentation without copy-pasting context.
+
+**Personal knowledge managers**: Discover forgotten documents related to your current work. Watch your knowledge base evolve over time through the visualization.
+
+## Try It Out
+
+Astrolabe is open source (AGPL) and ready to use. Your data universe has been waiting in the dark—it's time to turn on the lights.
+
+- **Install**: [Nextcloud App Store](https://apps.nextcloud.com/apps/astrolabe)
+- **Source**: [GitHub](https://github.com/cbcoutinho/nextcloud-mcp-server)
+- **Documentation**: [Setup Guide](https://github.com/cbcoutinho/nextcloud-mcp-server/tree/master/docs)
+- **Issues**: [Report bugs or request features](https://github.com/cbcoutinho/nextcloud-mcp-server/issues)
+
+---
+
+*Astrolabe is maintained by [Chris Coutinho](https://github.com/cbcoutinho). Contributions welcome.*

docs/configuration-migration-v2.md

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

docs/configuration.md

@@ -2,25 +2,82 @@
 
 The Nextcloud MCP server requires configuration to connect to your Nextcloud instance. Configuration is provided through environment variables, typically stored in a `.env` file.
 
+> **Note:** Configuration was significantly simplified in v0.58.0. If you're upgrading from v0.57.x, see the [Configuration Migration Guide](configuration-migration-v2.md).
+
 ## Quick Start
 
-Create a `.env` file based on `env.sample`:
+We provide mode-specific configuration templates for quick setup:
 
 ```bash
+# Choose a template based on your deployment mode:
+cp env.sample.single-user .env         # Simplest - one user, local dev
+cp env.sample.oauth-multi-user .env    # Recommended - multi-user OAuth
+cp env.sample.oauth-advanced .env      # Advanced - token exchange mode
+
+# Or start from the full example:
 cp env.sample .env
+
 # Edit .env with your Nextcloud details
 ```
 
-Then choose your authentication mode:
+Then choose your deployment mode:
 
-- [OAuth2/OIDC Configuration](#oauth2oidc-configuration) (Recommended)
-- [Basic Authentication Configuration](#basic-authentication-legacy)
+- [Single-User BasicAuth](#single-user-basicauth-mode) - Simplest for personal instances
+- [Multi-User OAuth](#multi-user-oauth-modes) - Recommended for production
+- [Deployment Mode Selection](#deployment-mode-selection) - Explicit mode declaration
 
 ---
 
-## OAuth2/OIDC Configuration
+## Deployment Mode Selection
 
-OAuth2/OIDC is the recommended authentication mode for production deployments.
+**New in v0.58.0:** You can explicitly declare your deployment mode to remove ambiguity and catch configuration errors early.
+
+```dotenv
+# Optional but recommended
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+```
+
+**Valid values:**
+- `single_user_basic` - Single-user with username/password
+- `multi_user_basic` - Multi-user with BasicAuth pass-through
+- `oauth_single_audience` - Multi-user OAuth (recommended)
+- `oauth_token_exchange` - Multi-user OAuth with token exchange
+- `smithery` - Smithery platform deployment
+
+**Benefits:**
+- ✅ Clear which mode is active
+- ✅ Better validation error messages
+- ✅ Self-documenting configuration
+- ✅ Catches configuration mistakes early
+
+**Auto-detection:** If `MCP_DEPLOYMENT_MODE` is not set, the server auto-detects the mode based on other settings (existing behavior).
+
+See [Authentication Modes](authentication.md) for detailed comparison of deployment modes.
+
+---
+
+## Single-User BasicAuth Mode
+
+BasicAuth with a single user is the simplest deployment mode. Use for personal instances, local development, and testing.
+
+```dotenv
+# Minimal single-user configuration
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Optional: Explicit mode declaration
+MCP_DEPLOYMENT_MODE=single_user_basic
+```
+
+> [!WARNING]
+> **Security Notice:** BasicAuth stores credentials in environment variables and is less secure than OAuth. Use OAuth for production multi-user deployments.
+
+---
+
+## Multi-User OAuth Modes
+
+OAuth2/OIDC is the recommended authentication mode for production multi-user deployments.
 
 ### Minimal Configuration (Auto-registration)
 
@@ -28,6 +85,9 @@ OAuth2/OIDC is the recommended authentication mode for production deployments.
 # .env file for OAuth with auto-registration
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
 # Leave these EMPTY for OAuth mode
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
@@ -41,6 +101,9 @@ This minimal configuration uses dynamic client registration to automatically reg
 # .env file for OAuth with pre-configured client
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
 
+# Optional: Explicit mode declaration (recommended)
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
 # OAuth Client Credentials (optional - auto-registers if not provided)
 NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
 NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
@@ -110,8 +173,50 @@ NEXTCLOUD_PASSWORD=your_app_password_or_password
 
 ## Semantic Search Configuration (Optional)
 
+**New in v0.58.0:** Simplified semantic search configuration with automatic dependency resolution.
+
 The MCP server includes semantic search capabilities powered by vector embeddings. This feature requires a vector database (Qdrant) and an embedding service.
 
+### Quick Start
+
+**Single-User Mode:**
+```dotenv
+NEXTCLOUD_HOST=http://localhost:8080
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# Enable semantic search
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector database
+QDRANT_LOCATION=:memory:
+
+# Embedding provider
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+**Multi-User OAuth Mode:**
+```dotenv
+NEXTCLOUD_HOST=https://nextcloud.example.com
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# Enable semantic search
+# In multi-user modes, this AUTOMATICALLY enables background operations!
+ENABLE_SEMANTIC_SEARCH=true
+
+# Required for background operations (auto-enabled by semantic search)
+TOKEN_ENCRYPTION_KEY=your-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# Vector database
+QDRANT_URL=http://qdrant:6333
+
+# Embedding provider
+OLLAMA_BASE_URL=http://ollama:11434
+```
+
+> **Note:** In multi-user modes (OAuth, Multi-User BasicAuth), enabling `ENABLE_SEMANTIC_SEARCH` automatically enables background operations and refresh token storage. You don't need to set `ENABLE_BACKGROUND_OPERATIONS` separately!
+
 ### Qdrant Vector Database Modes
 
 The server supports three Qdrant deployment modes:
@@ -126,7 +231,7 @@ No configuration needed! If neither `QDRANT_URL` nor `QDRANT_LOCATION` is set, t
 
 ```dotenv
 # No Qdrant configuration needed - defaults to :memory:
-VECTOR_SYNC_ENABLED=true
+ENABLE_SEMANTIC_SEARCH=true
 ```
 
 **Pros:**
@@ -145,7 +250,7 @@ For single-instance deployments that need persistence without a separate Qdrant
 ```dotenv
 # Local persistent storage
 QDRANT_LOCATION=/app/data/qdrant  # Or any writable path
-VECTOR_SYNC_ENABLED=true
+ENABLE_SEMANTIC_SEARCH=true
 ```
 
 **Pros:**
@@ -166,7 +271,7 @@ For production deployments with a dedicated Qdrant service:
 QDRANT_URL=http://qdrant:6333
 QDRANT_API_KEY=your-secret-api-key  # Optional
 QDRANT_COLLECTION=nextcloud_content  # Optional
-VECTOR_SYNC_ENABLED=true
+ENABLE_SEMANTIC_SEARCH=true
 ```
 
 **Pros:**
@@ -283,13 +388,15 @@ Solutions:
 - Data corruption in Qdrant
 - Confusing error messages during indexing
 
-### Vector Sync Configuration
+### Background Indexing Configuration
 
 Control background indexing behavior:
 
 ```dotenv
-# Vector sync settings (ADR-007)
-VECTOR_SYNC_ENABLED=true              # Enable background indexing
+# Semantic search (ADR-007, ADR-021)
+ENABLE_SEMANTIC_SEARCH=true           # Enable background indexing
+
+# Tuning parameters (advanced - only modify if needed)
 VECTOR_SYNC_SCAN_INTERVAL=300         # Scan interval in seconds (default: 5 minutes)
 VECTOR_SYNC_PROCESSOR_WORKERS=3       # Concurrent indexing workers (default: 3)
 VECTOR_SYNC_QUEUE_MAX_SIZE=10000      # Max queued documents (default: 10000)
@@ -299,6 +406,8 @@ DOCUMENT_CHUNK_SIZE=512               # Words per chunk (default: 512)
 DOCUMENT_CHUNK_OVERLAP=50             # Overlapping words between chunks (default: 50)
 ```
 
+> **Note:** The `VECTOR_SYNC_*` tuning parameters keep their names as they're implementation details. Only the user-facing feature flag was renamed to `ENABLE_SEMANTIC_SEARCH`.
+
 ### Embedding Service Configuration
 
 The server uses an embedding service to generate vector representations. Two options are available:
@@ -369,11 +478,11 @@ DOCUMENT_CHUNK_OVERLAP=100
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
+| `ENABLE_SEMANTIC_SEARCH` | ⚠️ Optional | `false` | Enable semantic search with background indexing (replaces `VECTOR_SYNC_ENABLED`) |
 | `QDRANT_URL` | ⚠️ Optional | - | Qdrant service URL (network mode) - mutually exclusive with `QDRANT_LOCATION` |
 | `QDRANT_LOCATION` | ⚠️ Optional | `:memory:` | Local Qdrant path (`:memory:` or `/path/to/data`) - mutually exclusive with `QDRANT_URL` |
 | `QDRANT_API_KEY` | ⚠️ Optional | - | Qdrant API key (network mode only) |
-| `QDRANT_COLLECTION` | ⚠️ Optional | `nextcloud_content` | Qdrant collection name |
-| `VECTOR_SYNC_ENABLED` | ⚠️ Optional | `false` | Enable background vector indexing |
+| `QDRANT_COLLECTION` | ⚠️ Optional | Auto-generated | Qdrant collection name |
 | `VECTOR_SYNC_SCAN_INTERVAL` | ⚠️ Optional | `300` | Document scan interval (seconds) |
 | `VECTOR_SYNC_PROCESSOR_WORKERS` | ⚠️ Optional | `3` | Concurrent indexing workers |
 | `VECTOR_SYNC_QUEUE_MAX_SIZE` | ⚠️ Optional | `10000` | Max queued documents |
@@ -383,6 +492,9 @@ DOCUMENT_CHUNK_OVERLAP=100
 | `DOCUMENT_CHUNK_SIZE` | ⚠️ Optional | `512` | Words per chunk for document embedding |
 | `DOCUMENT_CHUNK_OVERLAP` | ⚠️ Optional | `50` | Overlapping words between chunks (must be < chunk size) |
 
+**Deprecated variables (still functional):**
+- `VECTOR_SYNC_ENABLED` - Use `ENABLE_SEMANTIC_SEARCH` instead (will be removed in v1.0.0)
+
 ### Docker Compose Example
 
 Enable network mode Qdrant with docker-compose:
@@ -392,7 +504,7 @@ services:
   mcp:
     environment:
       - QDRANT_URL=http://qdrant:6333
-      - VECTOR_SYNC_ENABLED=true
+      - ENABLE_SEMANTIC_SEARCH=true
 
   qdrant:
     image: qdrant/qdrant:latest
@@ -419,6 +531,28 @@ docker-compose up
 
 ---
 
+## Astrolabe Internal URL
+
+The Astrolabe Nextcloud app may need to make internal HTTP requests to the local web server (e.g., for OAuth token refresh). By default, it uses `http://localhost` which works for standard Docker containers where PHP and Apache run together.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `astrolabe_internal_url` | Internal URL for server-to-server requests within container | `http://localhost` |
+
+**When to configure:**
+- Custom container setups where the internal web server is not on `localhost:80`
+- Kubernetes deployments with service discovery
+- Multi-container setups with separate web server containers
+
+**Example (Nextcloud config.php):**
+```php
+'astrolabe_internal_url' => 'http://web-server.internal:8080',
+```
+
+**Note:** This is for internal PHP-to-Apache requests, NOT for external client URLs. The default (`http://localhost`) works for standard Docker containers where PHP and Apache run together.
+
+---
+
 ## Loading Environment Variables
 
 After creating your `.env` file, load the environment variables:
@@ -545,6 +679,7 @@ uv run nextcloud-mcp-server --no-oauth \
 
 ## See Also
 
+- [Configuration Migration Guide v2](configuration-migration-v2.md) - **New in v0.58.0:** Migrate from old variable names
 - [OAuth Quick Start](quickstart-oauth.md) - 5-minute OAuth setup for development
 - [OAuth Setup Guide](oauth-setup.md) - Detailed OAuth configuration for production
 - [OAuth Architecture](oauth-architecture.md) - How OAuth works in the MCP server
@@ -553,3 +688,4 @@ uv run nextcloud-mcp-server --no-oauth \
 - [Running the Server](running.md) - Starting the server with different configurations
 - [Troubleshooting](troubleshooting.md) - Common configuration issues
 - [OAuth Troubleshooting](oauth-troubleshooting.md) - OAuth-specific troubleshooting
+- [ADR-021](ADR-021-configuration-consolidation.md) - Configuration consolidation architecture decision

docs/troubleshooting.md

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

docs/webhook-management-guide.md

@@ -0,0 +1,357 @@
+# 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** 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"
+```
+
+## Webhook Presets (via Astrolabe UI)
+
+The Astrolabe app provides preset webhook configurations that can be enabled/disabled via the Admin settings UI:
+
+| Preset | Events Covered |
+|--------|----------------|
+| `notes_sync` | File create/update/delete for .md files |
+| `calendar_sync` | Calendar object events |
+| `tables_sync` | Tables row events |
+| `forms_sync` | Forms submission events |
+| `files_sync` | All file events (optional, high volume) |
+
+**Enable Presets:**
+1. Navigate to **Nextcloud Settings → Astrolabe** (Admin settings)
+2. Toggle desired presets in "Webhook Configuration"
+
+**Note:** Presets require the MCP server's management API to be accessible. The API uses OAuth bearer tokens from the user's session.
+
+## 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 in Astrolabe
+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
+```

env.sample

@@ -1,203 +1,236 @@
-# Nextcloud Instance
+# ============================================
+# DEPLOYMENT MODE SELECTION
+# ============================================
+# Optional: Explicitly declare deployment mode (ADR-021)
+# If not set, mode is auto-detected from other settings
+# Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
+#               oauth_token_exchange, smithery
+#
+# Recommendation: Set this for clarity and to catch configuration errors early
+#MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# ============================================
+# COMMON SETTINGS (Required for all modes)
+# ============================================
+# Your Nextcloud instance URL (without trailing slash)
 NEXTCLOUD_HOST=
 
-# ===== AUTHENTICATION MODE =====
-# Choose ONE of the following:
-
-# Option 1: OAuth2/OIDC (RECOMMENDED - More Secure)
-# - Requires Nextcloud OIDC app installed and configured
-# - Admin must enable "Dynamic Client Registration" in OIDC app settings
-# - Leave NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD empty to use OAuth mode
-# - OAuth client credentials are stored encrypted in SQLite (TOKEN_STORAGE_DB)
-# - Optional: Pre-register client and provide credentials (otherwise auto-registers)
-NEXTCLOUD_OIDC_CLIENT_ID=
-NEXTCLOUD_OIDC_CLIENT_SECRET=
-NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
-
-# OAuth Storage Configuration (SQLite storage for OAuth clients and refresh tokens)
-# TOKEN_ENCRYPTION_KEY: Required for encrypting OAuth client secrets and refresh tokens
-# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-#TOKEN_ENCRYPTION_KEY=
-# TOKEN_STORAGE_DB: Path to SQLite database (default: /app/data/tokens.db)
-#TOKEN_STORAGE_DB=/app/data/tokens.db
-
-# ===== ADR-004 PROGRESSIVE CONSENT CONFIGURATION =====
-# Enable Progressive Consent mode (dual OAuth flows)
-# When enabled: Flow 1 for client auth, Flow 2 for Nextcloud resource access
-# When disabled: Uses existing hybrid flow (backward compatible)
-
-# MCP Server OAuth Client Configuration
-# The MCP server's own OAuth client credentials for Flow 2
-# If not set, will use dynamic client registration
-#MCP_SERVER_CLIENT_ID=
-#MCP_SERVER_CLIENT_SECRET=
-
-# Allowed MCP Client IDs (comma-separated list)
-# Client IDs that are allowed to authenticate in Flow 1
-# Examples: claude-desktop,continue-dev,zed-editor
-#ALLOWED_MCP_CLIENTS=claude-desktop,continue-dev,zed-editor
-
-# Token cache configuration for Token Broker Service
-# Cache TTL in seconds (default: 300 = 5 minutes)
-#TOKEN_CACHE_TTL=300
-# Early refresh threshold in seconds (default: 30)
-#TOKEN_CACHE_EARLY_REFRESH=30
-
-# Option 2: Basic Authentication (LEGACY - Less Secure)
-# - Requires username and password
-# - Credentials stored in environment variables
-# - Use only for backward compatibility or if OAuth unavailable
-# - If these are set, OAuth mode is disabled
+# ============================================
+# SINGLE-USER BASICAUTH MODE
+# ============================================
+# Simplest deployment - one user, credentials in environment
+# Use for: Personal instances, local development, testing
+#
+# Required:
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
 
+# ============================================
+# MULTI-USER BASICAUTH MODE
+# ============================================
+# Users provide credentials in request headers (pass-through)
+# Use for: Multi-user without OAuth, simple shared deployments
+#
+# Required:
+#ENABLE_MULTI_USER_BASIC_AUTH=true
+#
+# Optional - Background Operations (for semantic search, future features):
+# Enable background token storage using app passwords (via Astrolabe)
+# Required for semantic search in multi-user mode
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
+#ENABLE_BACKGROUND_OPERATIONS=true
+#NEXTCLOUD_OIDC_CLIENT_ID=
+#NEXTCLOUD_OIDC_CLIENT_SECRET=
+#TOKEN_ENCRYPTION_KEY=
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
+
+# ============================================
+# OAUTH SINGLE-AUDIENCE MODE (Recommended)
+# ============================================
+# Multi-user OAuth with single-audience tokens
+# Use for: Multi-user production deployments, enhanced security
+# Tokens work for both MCP server and Nextcloud APIs (pass-through)
+#
+# Required: None (uses Dynamic Client Registration if credentials not provided)
+#
+# Optional - Pre-registered OAuth Client:
+# If you pre-register the client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=
+#NEXTCLOUD_OIDC_CLIENT_SECRET=
+#
+# Optional - Background Operations (for semantic search, future features):
+# Enable refresh token storage for offline access
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
+#ENABLE_BACKGROUND_OPERATIONS=true
+#TOKEN_ENCRYPTION_KEY=
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+#
+# Optional - Custom OIDC Discovery:
+# Auto-detected from NEXTCLOUD_HOST if not set
+#NEXTCLOUD_OIDC_DISCOVERY_URL=
+#
+# Optional - Custom Scopes:
+# Default: openid profile email offline_access notes:* calendar:* contacts:* tables:* webdav:* deck:* cookbook:*
+#NEXTCLOUD_OIDC_SCOPES=openid profile email notes:* calendar:*
+#
+# MCP Server URL (for OAuth redirects):
+#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
+
+# ============================================
+# OAUTH TOKEN EXCHANGE MODE (Advanced)
+# ============================================
+# Multi-user OAuth with RFC 8693 token exchange
+# Use for: Advanced deployments requiring separate MCP and Nextcloud tokens
+# MCP tokens are separate from Nextcloud tokens
+#
+# Required:
+#ENABLE_TOKEN_EXCHANGE=true
+#
+# Optional - Pre-registered OAuth Client:
+# If you pre-register the client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=
+#NEXTCLOUD_OIDC_CLIENT_SECRET=
+#
+# Optional - Token Exchange Configuration:
+# Cache TTL in seconds (default: 300 = 5 minutes)
+#TOKEN_EXCHANGE_CACHE_TTL=300
+#
+# Optional - Background Operations:
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables this in multi-user modes
+#ENABLE_BACKGROUND_OPERATIONS=true
+#TOKEN_ENCRYPTION_KEY=
+#TOKEN_STORAGE_DB=/app/data/tokens.db
+#
+# Optional - Custom OIDC Discovery:
+#NEXTCLOUD_OIDC_DISCOVERY_URL=
+#
+# MCP Server URL (for OAuth redirects):
+#NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+#
+# Optional features (semantic search, document processing):
+# See "Optional Features" section below
+
+# ============================================
+# SMITHERY STATELESS MODE
+# ============================================
+# Stateless multi-tenant deployment for Smithery platform
+# Configuration comes from session URL parameters
+# No persistent storage, no OAuth, no vector sync
+#
+# Required: None (all config from session URL)
+# This mode is activated automatically when deployed to Smithery
+
+# ============================================
+# OPTIONAL FEATURES (All Deployment Modes)
+# ============================================
+
+# ===== SEMANTIC SEARCH =====
+# AI-powered semantic search across Nextcloud content
+# Requires: Qdrant vector database + embedding provider (Ollama, Bedrock, or Simple fallback)
+#
+# Enable semantic search:
+#ENABLE_SEMANTIC_SEARCH=true
+#
+# Note for Multi-User Modes:
+# ENABLE_SEMANTIC_SEARCH automatically enables background operations when needed
+# No need to set ENABLE_BACKGROUND_OPERATIONS separately
+# The server will automatically request refresh tokens and store them encrypted
+#
+# Vector Database - Choose ONE mode:
+# 1. In-memory (default): Set neither QDRANT_URL nor QDRANT_LOCATION
+# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
+# 3. Network: Set QDRANT_URL=http://qdrant:6333
+#
+#QDRANT_URL=http://qdrant:6333
+#QDRANT_LOCATION=:memory:
+#QDRANT_API_KEY=
+#QDRANT_COLLECTION=nextcloud_content
+#
+# Embedding Provider - Choose ONE:
+# 1. Ollama (recommended for local deployment):
+#OLLAMA_BASE_URL=http://ollama:11434
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+#OLLAMA_VERIFY_SSL=true
+#
+# 2. Amazon Bedrock (for AWS deployments):
+#AWS_REGION=us-east-1
+#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+# Optional: AWS credentials (uses credential chain if not set)
+#AWS_ACCESS_KEY_ID=
+#AWS_SECRET_ACCESS_KEY=
+#
+# 3. Simple (automatic fallback, no configuration needed)
+# Uses basic in-memory embeddings if no provider configured
+#
+# Document Chunking:
+# Configure how documents are split before embedding
+#DOCUMENT_CHUNK_SIZE=512
+#DOCUMENT_CHUNK_OVERLAP=50
+
+# ===== SEMANTIC SEARCH TUNING =====
+# Advanced parameters for vector sync background operations
+# Only modify if you understand the implications
+#
+# Document scan interval in seconds (default: 300 = 5 minutes)
+#VECTOR_SYNC_SCAN_INTERVAL=300
+#
+# Concurrent indexing workers (default: 3)
+#VECTOR_SYNC_PROCESSOR_WORKERS=3
+#
+# Max queued documents (default: 10000)
+#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
+
+# ===== DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX, etc. for semantic search
+# Disabled by default
+#
+#ENABLE_DOCUMENT_PROCESSING=false
+#DOCUMENT_PROCESSOR=unstructured
+#
+# Unstructured.io Processor (recommended):
+#ENABLE_UNSTRUCTURED=false
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+#UNSTRUCTURED_TIMEOUT=120
+#UNSTRUCTURED_STRATEGY=auto
+#UNSTRUCTURED_LANGUAGES=eng,deu
+#PROGRESS_INTERVAL=10
+#
+# Tesseract OCR (lightweight, images only):
+#ENABLE_TESSERACT=false
+#TESSERACT_CMD=/usr/bin/tesseract
+#TESSERACT_LANG=eng
+#
+# Custom Processor (your own API):
+#ENABLE_CUSTOM_PROCESSOR=false
+#CUSTOM_PROCESSOR_NAME=my_ocr
+#CUSTOM_PROCESSOR_URL=http://localhost:9000/process
+#CUSTOM_PROCESSOR_API_KEY=
+#CUSTOM_PROCESSOR_TIMEOUT=60
+#CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png
+
+# ===== SECURITY & ADVANCED =====
 # Cookie security (browser UI)
 # Auto-detects from NEXTCLOUD_HOST protocol if not set
-# Set explicitly for non-standard setups
 #COOKIE_SECURE=true
 
 # ============================================
-# Document Processing Configuration
+# DEPRECATED VARIABLES (Backward Compatibility)
 # ============================================
-# Enable document processing (PDF, DOCX, images, etc.)
-# Set to false to disable all document processing
-ENABLE_DOCUMENT_PROCESSING=false
-
-# Default processor to use when multiple are available
-# Options: unstructured, tesseract, custom
-DOCUMENT_PROCESSOR=unstructured
-
-# ============================================
-# Unstructured.io Processor
-# ============================================
-# Enable Unstructured processor (requires unstructured service in docker-compose)
-# This is a cloud-based/API processor supporting many document types
-ENABLE_UNSTRUCTURED=false
-
-# Unstructured API endpoint
-UNSTRUCTURED_API_URL=http://unstructured:8000
-
-# Request timeout in seconds (default: 120)
-# OCR operations can take 30-120 seconds for large documents
-UNSTRUCTURED_TIMEOUT=120
-
-# Parsing strategy: auto, fast, hi_res
-# - auto: Automatically choose based on document type
-# - fast: Fast parsing without OCR
-# - hi_res: High-resolution with OCR (slowest, most accurate)
-UNSTRUCTURED_STRATEGY=auto
-
-# OCR languages (comma-separated ISO 639-3 codes)
-# Common: eng=English, deu=German, fra=French, spa=Spanish
-UNSTRUCTURED_LANGUAGES=eng,deu
-
-# Progress reporting interval in seconds (default: 10)
-# During long-running OCR operations, progress notifications are sent to the MCP client
-# at this interval to prevent timeouts and provide status updates
-PROGRESS_INTERVAL=10
-
-# ============================================
-# Tesseract Processor (Local OCR)
-# ============================================
-# Enable Tesseract processor (requires tesseract binary installed)
-# This is a local, lightweight OCR solution for images only
-ENABLE_TESSERACT=false
-
-# Path to tesseract executable (optional, auto-detected if in PATH)
-#TESSERACT_CMD=/usr/bin/tesseract
-
-# OCR language (e.g., eng, deu, eng+deu for multiple)
-TESSERACT_LANG=eng
-
-# ============================================
-# Custom Processor (Your own API)
-# ============================================
-# Enable custom document processor via HTTP API
-ENABLE_CUSTOM_PROCESSOR=false
-
-# Unique name for your processor
-#CUSTOM_PROCESSOR_NAME=my_ocr
-
-# Your custom processor API endpoint
-#CUSTOM_PROCESSOR_URL=http://localhost:9000/process
-
-# Optional API key for authentication
-#CUSTOM_PROCESSOR_API_KEY=your-api-key-here
-
-# Request timeout in seconds
-#CUSTOM_PROCESSOR_TIMEOUT=60
-
-# Comma-separated MIME types your processor supports
-#CUSTOM_PROCESSOR_TYPES=application/pdf,image/jpeg,image/png
-
-# ============================================
-# Semantic Search & Vector Sync Configuration
-# ============================================
-# EXPERIMENTAL: Semantic search for Notes app (multi-app support planned)
-# Requires: Qdrant vector database + Ollama embedding service
-# Disabled by default
-
-# Enable background vector indexing
-VECTOR_SYNC_ENABLED=false
-
-# Document scan interval in seconds (default: 300 = 5 minutes)
-# How often to check for new/updated documents
-#VECTOR_SYNC_SCAN_INTERVAL=300
-
-# Concurrent indexing workers (default: 3)
-# Number of parallel workers for embedding generation
-#VECTOR_SYNC_PROCESSOR_WORKERS=3
-
-# Max queued documents (default: 10000)
-# Maximum documents waiting to be processed
-#VECTOR_SYNC_QUEUE_MAX_SIZE=10000
-
-# ============================================
-# Qdrant Vector Database Configuration
-# ============================================
-# Choose ONE of three modes:
-# 1. In-memory mode (default): Set neither QDRANT_URL nor QDRANT_LOCATION
-# 2. Persistent local: Set QDRANT_LOCATION=/path/to/data
-# 3. Network mode: Set QDRANT_URL=http://qdrant:6333
-
-# Network mode: URL to Qdrant service
-#QDRANT_URL=http://qdrant:6333
-
-# Local mode: Path to store vectors (use :memory: for in-memory)
-#QDRANT_LOCATION=:memory:
-
-# API key for network mode (optional)
-#QDRANT_API_KEY=
-
-# Collection name (optional - auto-generated if not set)
-# Auto-generation format: {deployment-id}-{model-name}
-# Allows safe model switching and multi-server deployments
-#QDRANT_COLLECTION=nextcloud_content
-
-# ============================================
-# Ollama Embedding Service Configuration
-# ============================================
-# Ollama endpoint for embeddings (if not set, uses SimpleEmbeddingProvider fallback)
-#OLLAMA_BASE_URL=http://ollama:11434
-
-# Embedding model to use (default: nomic-embed-text, 768 dimensions)
-# Changing this creates a new collection (requires re-embedding all documents)
-#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
-
-# Verify SSL certificates (default: true)
-#OLLAMA_VERIFY_SSL=true
-
-# ============================================
-# Document Chunking Configuration
-# ============================================
-# Configure how documents are split before embedding
-
-# Words per chunk (default: 512)
-# Smaller chunks (256-384): More precise, less context, more storage
-# Larger chunks (768-1024): More context, less precise, less storage
-#DOCUMENT_CHUNK_SIZE=512
-
-# Overlapping words between chunks (default: 50)
-# Recommended: 10-20% of chunk size
-# Preserves context across chunk boundaries
-#DOCUMENT_CHUNK_OVERLAP=50
+# These variables still work but will be removed in v1.0.0
+# Please migrate to new names:
+#
+# Old Name                  → New Name
+# VECTOR_SYNC_ENABLED      → ENABLE_SEMANTIC_SEARCH
+# ENABLE_OFFLINE_ACCESS    → ENABLE_BACKGROUND_OPERATIONS
+#
+# Migration is optional - both old and new names work
+# Deprecation warnings will be logged when old names are used

env.sample.oauth-advanced

@@ -0,0 +1,80 @@
+# ============================================
+# OAUTH TOKEN EXCHANGE QUICK START (Advanced)
+# ============================================
+# Advanced OAuth deployment with RFC 8693 token exchange
+# Use for: Deployments requiring separate MCP and Nextcloud tokens
+# Features: Dual-audience tokens, enhanced security boundaries
+#
+# Copy this file to .env and configure
+
+# ===== REQUIRED SETTINGS =====
+# Your Nextcloud instance URL (without trailing slash)
+NEXTCLOUD_HOST=https://nextcloud.example.com
+
+# Enable token exchange mode
+ENABLE_TOKEN_EXCHANGE=true
+
+# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
+# OAuth mode activates when these are NOT set
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
+# Recommended for clarity
+MCP_DEPLOYMENT_MODE=oauth_token_exchange
+
+# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
+# If you pre-register the OAuth client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
+#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
+
+# MCP Server URL (for OAuth redirects)
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# ===== OPTIONAL: TOKEN EXCHANGE TUNING =====
+# Cache TTL for exchanged tokens (default: 300 seconds = 5 minutes)
+TOKEN_EXCHANGE_CACHE_TTL=300
+
+# ===== OPTIONAL: SEMANTIC SEARCH =====
+# AI-powered semantic search with automatic background operation setup
+#
+# Note: ENABLE_SEMANTIC_SEARCH automatically enables background operations
+# in token exchange mode, just like in OAuth single-audience mode
+#
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector Database (required for semantic search)
+QDRANT_URL=http://qdrant:6333
+
+# Embedding Provider (required for semantic search)
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Token Storage (required for background operations - auto-enabled by semantic search)
+# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+TOKEN_ENCRYPTION_KEY=your-encryption-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ===== OPTIONAL: DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX for semantic search
+#ENABLE_DOCUMENT_PROCESSING=true
+#ENABLE_UNSTRUCTURED=true
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# ===== TOKEN EXCHANGE MODE EXPLANATION =====
+# In this mode:
+# 1. MCP clients authenticate with tokens scoped to "mcp-server" audience
+# 2. Server exchanges MCP tokens for Nextcloud tokens on each request
+# 3. Provides clear separation between MCP session and Nextcloud access
+# 4. Enables fine-grained token lifecycle management
+#
+# When to use:
+# - Strict security requirements (separate token contexts)
+# - Complex multi-service architectures
+# - Need independent token expiration policies
+#
+# When NOT to use:
+# - Simple deployments (use oauth_single_audience instead)
+# - High-performance requirements (token exchange adds latency)
+
+# For more configuration options, see env.sample

env.sample.oauth-multi-user

@@ -0,0 +1,77 @@
+# ============================================
+# OAUTH MULTI-USER QUICK START (Recommended)
+# ============================================
+# Multi-user deployment with OAuth authentication
+# Use for: Multi-user production deployments, enhanced security
+# Features: Single-audience tokens, automatic client registration (DCR)
+#
+# Copy this file to .env and configure
+
+# ===== REQUIRED SETTINGS =====
+# Your Nextcloud instance URL (without trailing slash)
+NEXTCLOUD_HOST=https://nextcloud.example.com
+
+# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
+# OAuth mode activates when these are NOT set
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
+# Recommended for clarity
+MCP_DEPLOYMENT_MODE=oauth_single_audience
+
+# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
+# If you pre-register the OAuth client instead of using DCR:
+#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
+#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
+
+# MCP Server URL (for OAuth redirects)
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# ===== OPTIONAL: SEMANTIC SEARCH (Recommended) =====
+# AI-powered semantic search with automatic background operation setup
+#
+# When you enable semantic search in multi-user mode:
+# 1. ENABLE_SEMANTIC_SEARCH automatically enables background operations
+# 2. Server requests refresh tokens for offline indexing
+# 3. Tokens are stored encrypted in TOKEN_STORAGE_DB
+# 4. No need to set ENABLE_BACKGROUND_OPERATIONS separately!
+#
+ENABLE_SEMANTIC_SEARCH=true
+
+# Vector Database (required for semantic search)
+QDRANT_URL=http://qdrant:6333
+# OR for in-memory mode:
+#QDRANT_LOCATION=:memory:
+
+# Embedding Provider (required for semantic search)
+# Option 1: Ollama (recommended for local deployment)
+OLLAMA_BASE_URL=http://ollama:11434
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# Option 2: Amazon Bedrock (for AWS deployments)
+#AWS_REGION=us-east-1
+#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
+
+# Token Storage (required for background operations - auto-enabled by semantic search)
+# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+TOKEN_ENCRYPTION_KEY=your-encryption-key-here
+TOKEN_STORAGE_DB=/app/data/tokens.db
+
+# ===== OPTIONAL: DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX for semantic search
+#ENABLE_DOCUMENT_PROCESSING=true
+#ENABLE_UNSTRUCTURED=true
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# ===== SUMMARY OF AUTO-ENABLEMENT =====
+# With ENABLE_SEMANTIC_SEARCH=true in OAuth mode:
+# ✅ Background operations enabled automatically
+# ✅ Refresh token storage enabled automatically
+# ✅ OAuth credentials required (DCR or pre-registered)
+# ✅ Encryption key required for token storage
+#
+# You only need to set ENABLE_SEMANTIC_SEARCH and provide the required
+# infrastructure (Qdrant, Ollama, encryption key). The rest is automatic!
+
+# For more advanced configuration, see env.sample

env.sample.single-user

@@ -0,0 +1,37 @@
+# ============================================
+# SINGLE-USER BASICAUTH QUICK START
+# ============================================
+# Simplest deployment mode - one user, credentials in environment
+# Use for: Personal instances, local development, testing
+#
+# Copy this file to .env and fill in your credentials
+
+# ===== REQUIRED SETTINGS =====
+# Your Nextcloud instance URL (without trailing slash)
+NEXTCLOUD_HOST=http://localhost:8080
+
+# Your Nextcloud credentials
+NEXTCLOUD_USERNAME=admin
+NEXTCLOUD_PASSWORD=password
+
+# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
+# Recommended to avoid ambiguity
+MCP_DEPLOYMENT_MODE=single_user_basic
+
+# ===== OPTIONAL: SEMANTIC SEARCH =====
+# Uncomment to enable AI-powered semantic search
+# Requires: Qdrant + embedding provider (Ollama or Bedrock)
+#
+#ENABLE_SEMANTIC_SEARCH=true
+#QDRANT_LOCATION=:memory:
+#OLLAMA_BASE_URL=http://ollama:11434
+#OLLAMA_EMBEDDING_MODEL=nomic-embed-text
+
+# ===== OPTIONAL: DOCUMENT PROCESSING =====
+# Extract text from PDFs, images, DOCX for semantic search
+#ENABLE_DOCUMENT_PROCESSING=true
+#ENABLE_UNSTRUCTURED=true
+#UNSTRUCTURED_API_URL=http://unstructured:8000
+
+# That's it! Single-user mode is the simplest to configure.
+# For more options, see env.sample

nextcloud_mcp_server/alembic/versions/20260113_1200_002_add_app_passwords.py

@@ -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")

nextcloud_mcp_server/api/__init__.py

@@ -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",
+]

nextcloud_mcp_server/api/passwords.py

@@ -0,0 +1,429 @@
+"""App password management API endpoints.
+
+Provides REST API endpoints for app password provisioning in multi-user BasicAuth mode.
+These endpoints are used by the Nextcloud PHP app (Astrolabe) to:
+- Store app passwords for background sync operations
+- Check app password status
+- Delete stored app passwords
+
+Authentication is via BasicAuth with the user's Nextcloud credentials.
+Passwords are validated against Nextcloud before being stored.
+"""
+
+import base64
+import logging
+import re
+import time
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+if TYPE_CHECKING:
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+from nextcloud_mcp_server.api.management import _sanitize_error_for_client
+
+logger = logging.getLogger(__name__)
+
+# App password format regex (Nextcloud format: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx)
+APP_PASSWORD_PATTERN = re.compile(
+    r"^[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}-[a-zA-Z0-9]{5}$"
+)
+
+# Timeout for Nextcloud API validation requests (seconds)
+NEXTCLOUD_VALIDATION_TIMEOUT = 10.0
+
+# Rate limiting configuration for app password provisioning
+# Limits: 5 attempts per user per hour
+RATE_LIMIT_MAX_ATTEMPTS = 5
+RATE_LIMIT_WINDOW_SECONDS = 3600  # 1 hour
+
+# In-memory rate limiter storage
+# Structure: {user_id: [(timestamp, success), ...]}
+_rate_limit_attempts: dict[str, list[tuple[float, bool]]] = defaultdict(list)
+
+
+def _check_rate_limit(user_id: str) -> tuple[bool, int]:
+    """Check if user is rate limited for app password operations.
+
+    Implements a sliding window rate limiter to prevent brute-force attacks
+    on the app password provisioning endpoint.
+
+    Args:
+        user_id: User identifier to check
+
+    Returns:
+        Tuple of (is_allowed, seconds_until_retry)
+        - is_allowed: True if request should be allowed
+        - seconds_until_retry: Seconds to wait if rate limited (0 if allowed)
+    """
+    current_time = time.time()
+    window_start = current_time - RATE_LIMIT_WINDOW_SECONDS
+
+    # Clean up old attempts outside the window
+    _rate_limit_attempts[user_id] = [
+        (ts, success)
+        for ts, success in _rate_limit_attempts[user_id]
+        if ts > window_start
+    ]
+
+    # Count recent attempts (both successful and failed)
+    recent_attempts = len(_rate_limit_attempts[user_id])
+
+    if recent_attempts >= RATE_LIMIT_MAX_ATTEMPTS:
+        # Find when the oldest attempt in the window will expire
+        oldest_attempt = min(ts for ts, _ in _rate_limit_attempts[user_id])
+        seconds_until_retry = int(
+            oldest_attempt + RATE_LIMIT_WINDOW_SECONDS - current_time
+        )
+        return False, max(1, seconds_until_retry)
+
+    return True, 0
+
+
+def _record_rate_limit_attempt(user_id: str, success: bool) -> None:
+    """Record an app password provisioning attempt for rate limiting.
+
+    Args:
+        user_id: User identifier
+        success: Whether the attempt was successful
+    """
+    _rate_limit_attempts[user_id].append((time.time(), success))
+
+
+def _extract_basic_auth(
+    request: Request, path_user_id: str
+) -> tuple[str, str, JSONResponse | None]:
+    """Extract and validate BasicAuth credentials from request.
+
+    Validates:
+    1. Authorization header is present and valid BasicAuth format
+    2. Username in credentials matches the path user_id
+
+    Args:
+        request: Starlette request with Authorization header
+        path_user_id: User ID from the URL path to verify against
+
+    Returns:
+        Tuple of (username, password, error_response)
+        - If successful: (username, password, None)
+        - If failed: ("", "", JSONResponse with error)
+    """
+    auth_header = request.headers.get("Authorization")
+
+    if not auth_header or not auth_header.startswith("Basic "):
+        return (
+            "",
+            "",
+            JSONResponse(
+                {"success": False, "error": "Missing BasicAuth credentials"},
+                status_code=401,
+            ),
+        )
+
+    try:
+        # Decode BasicAuth
+        encoded = auth_header.split(" ", 1)[1]
+        decoded = base64.b64decode(encoded).decode("utf-8")
+        username, password = decoded.split(":", 1)
+    except Exception:
+        return (
+            "",
+            "",
+            JSONResponse(
+                {"success": False, "error": "Invalid BasicAuth format"},
+                status_code=401,
+            ),
+        )
+
+    # Verify username matches path user_id
+    if username != path_user_id:
+        logger.warning(
+            f"Username mismatch in app password operation for path user {path_user_id}"
+        )
+        return (
+            "",
+            "",
+            JSONResponse(
+                {"success": False, "error": "Username does not match path user_id"},
+                status_code=403,
+            ),
+        )
+
+    return username, password, None
+
+
+async def _get_app_password_storage(request: Request) -> "RefreshTokenStorage":
+    """Get or initialize RefreshTokenStorage for app password operations.
+
+    Checks app.state.storage first, then falls back to creating from environment.
+    This helper avoids repeated storage initialization logic across endpoints.
+
+    Args:
+        request: Starlette request with app state
+
+    Returns:
+        Initialized RefreshTokenStorage instance
+    """
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+    storage = getattr(request.app.state, "storage", None)
+
+    if not storage:
+        # Multi-user BasicAuth mode may not have oauth_context
+        # Initialize storage from environment
+        storage = RefreshTokenStorage.from_env()
+        await storage.initialize()
+
+    return storage
+
+
+async def provision_app_password(request: Request) -> JSONResponse:
+    """POST /api/v1/users/{user_id}/app-password - Store app password for background sync.
+
+    This endpoint is used by Astrolabe (Nextcloud PHP app) to provision app passwords
+    for multi-user BasicAuth mode background sync.
+
+    The request must include BasicAuth credentials where:
+    - username: Nextcloud user ID (must match path user_id)
+    - password: The app password being provisioned
+
+    The MCP server validates the app password against Nextcloud before storing it.
+    This proves the user owns the password and has access to Nextcloud.
+
+    Security model:
+    - User identity is verified via BasicAuth against Nextcloud
+    - App password is encrypted before storage
+    - Only the user who owns the password can provision it
+    - Rate limited to prevent brute-force attacks
+    """
+    from nextcloud_mcp_server.config import get_settings
+
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    # Check rate limit before processing
+    is_allowed, retry_after = _check_rate_limit(path_user_id)
+    if not is_allowed:
+        logger.warning(
+            f"Rate limit exceeded for app password provisioning: {path_user_id}"
+        )
+        return JSONResponse(
+            {
+                "success": False,
+                "error": f"Rate limit exceeded. Try again in {retry_after} seconds.",
+            },
+            status_code=429,
+            headers={"Retry-After": str(retry_after)},
+        )
+
+    # Extract and validate BasicAuth credentials
+    username, app_password, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        _record_rate_limit_attempt(path_user_id, success=False)
+        return error_response
+
+    # Validate app password format
+    if not APP_PASSWORD_PATTERN.match(app_password):
+        _record_rate_limit_attempt(path_user_id, success=False)
+        return JSONResponse(
+            {"success": False, "error": "Invalid app password format"},
+            status_code=400,
+        )
+
+    # Get Nextcloud host from settings
+    settings = get_settings()
+    nextcloud_host = settings.nextcloud_host
+
+    if not nextcloud_host:
+        logger.error("NEXTCLOUD_HOST not configured")
+        return JSONResponse(
+            {"success": False, "error": "Server not configured"},
+            status_code=500,
+        )
+
+    # Validate app password against Nextcloud
+    try:
+        async with httpx.AsyncClient(timeout=NEXTCLOUD_VALIDATION_TIMEOUT) as client:
+            # Use OCS API to verify credentials
+            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
+            response = await client.get(
+                test_url,
+                auth=(username, app_password),
+                params={"format": "json"},
+                headers={"OCS-APIRequest": "true"},
+            )
+
+            if response.status_code != 200:
+                logger.warning(
+                    f"App password validation failed for user: HTTP {response.status_code}"
+                )
+                _record_rate_limit_attempt(path_user_id, success=False)
+                return JSONResponse(
+                    {"success": False, "error": "Invalid app password"},
+                    status_code=401,
+                )
+
+            # Verify the user ID from response matches
+            data = response.json()
+            ocs_user_id = data.get("ocs", {}).get("data", {}).get("id")
+            if ocs_user_id != username:
+                logger.warning("User ID mismatch in OCS response")
+                _record_rate_limit_attempt(path_user_id, success=False)
+                return JSONResponse(
+                    {"success": False, "error": "User ID mismatch"},
+                    status_code=403,
+                )
+
+    except httpx.RequestError as e:
+        logger.error(f"Failed to validate app password: {e}")
+        return JSONResponse(
+            {"success": False, "error": "Failed to validate credentials"},
+            status_code=500,
+        )
+
+    # Store the validated app password
+    try:
+        storage = await _get_app_password_storage(request)
+        await storage.store_app_password(username, app_password)
+
+        _record_rate_limit_attempt(path_user_id, success=True)
+        logger.info(f"Provisioned app password for user: {username}")
+
+        return JSONResponse(
+            {
+                "success": True,
+                "message": f"App password stored for {username}",
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "provision_app_password")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )
+
+
+async def get_app_password_status(request: Request) -> JSONResponse:
+    """GET /api/v1/users/{user_id}/app-password - Check if user has provisioned app password.
+
+    Returns status of background sync access for multi-user BasicAuth mode.
+
+    Requires BasicAuth with the user's app password for authentication.
+    """
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    # Extract and validate BasicAuth credentials
+    username, _, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        return error_response
+
+    try:
+        storage = await _get_app_password_storage(request)
+        app_password = await storage.get_app_password(username)
+
+        return JSONResponse(
+            {
+                "success": True,
+                "user_id": username,
+                "has_app_password": app_password is not None,
+            }
+        )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "get_app_password_status")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )
+
+
+async def delete_app_password(request: Request) -> JSONResponse:
+    """DELETE /api/v1/users/{user_id}/app-password - Delete stored app password.
+
+    Removes the user's app password from MCP server storage.
+
+    Requires BasicAuth with the user's credentials.
+    """
+    from nextcloud_mcp_server.config import get_settings
+
+    # Get user_id from path
+    path_user_id = request.path_params.get("user_id")
+    if not path_user_id:
+        return JSONResponse(
+            {"success": False, "error": "Missing user_id in path"},
+            status_code=400,
+        )
+
+    # Extract and validate BasicAuth credentials
+    username, password, error_response = _extract_basic_auth(request, path_user_id)
+    if error_response is not None:
+        return error_response
+
+    # Validate credentials against Nextcloud
+    settings = get_settings()
+    nextcloud_host = settings.nextcloud_host
+
+    try:
+        async with httpx.AsyncClient(timeout=NEXTCLOUD_VALIDATION_TIMEOUT) as client:
+            test_url = f"{nextcloud_host}/ocs/v1.php/cloud/user"
+            response = await client.get(
+                test_url,
+                auth=(username, password),
+                params={"format": "json"},
+                headers={"OCS-APIRequest": "true"},
+            )
+
+            if response.status_code != 200:
+                return JSONResponse(
+                    {"success": False, "error": "Invalid credentials"},
+                    status_code=401,
+                )
+    except httpx.RequestError as e:
+        logger.error(f"Failed to validate credentials: {e}")
+        return JSONResponse(
+            {"success": False, "error": "Failed to validate credentials"},
+            status_code=500,
+        )
+
+    try:
+        storage = await _get_app_password_storage(request)
+        deleted = await storage.delete_app_password(username)
+
+        if deleted:
+            logger.info(f"Deleted app password for user: {username}")
+            return JSONResponse(
+                {
+                    "success": True,
+                    "message": f"App password deleted for {username}",
+                }
+            )
+        else:
+            return JSONResponse(
+                {
+                    "success": True,
+                    "message": "No app password found to delete",
+                }
+            )
+
+    except Exception as e:
+        error_msg = _sanitize_error_for_client(e, "delete_app_password")
+        return JSONResponse(
+            {"success": False, "error": error_msg},
+            status_code=500,
+        )

nextcloud_mcp_server/api/visualization.py

@@ -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,
+        )

nextcloud_mcp_server/api/webhooks.py

@@ -0,0 +1,308 @@
+"""Webhook management API endpoints.
+
+Provides REST API endpoints for managing webhook registrations with Nextcloud.
+These endpoints are used by the Nextcloud PHP app (Astrolabe) to:
+- List installed Nextcloud apps
+- Create, list, and delete webhook registrations
+
+All endpoints require OAuth bearer token authentication via UnifiedTokenVerifier.
+"""
+
+import logging
+
+import httpx
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from nextcloud_mcp_server.api.management import (
+    _sanitize_error_for_client,
+    extract_bearer_token,
+    validate_token_and_get_user,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def get_installed_apps(request: Request) -> JSONResponse:
+    """GET /api/v1/apps - Get list of installed Nextcloud apps.
+
+    Returns a list of installed app IDs for filtering webhook presets.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/apps: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "get_installed_apps"),
+            },
+            status_code=401,
+        )
+
+    try:
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with httpx.AsyncClient(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Get installed apps using OCS API
+            # Notes, Calendar, Deck, Tables, etc. are apps that support webhooks
+            # We check which ones are installed and enabled
+            ocs_url = "/ocs/v1.php/cloud/apps"
+            params = {"filter": "enabled"}
+
+            response = await client.get(
+                ocs_url,
+                params=params,
+                headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+            )
+
+            if response.status_code != 200:
+                raise ValueError(f"OCS API returned status {response.status_code}")
+
+            data = response.json()
+            apps = data.get("ocs", {}).get("data", {}).get("apps", [])
+
+            return JSONResponse({"apps": apps})
+
+    except Exception as e:
+        logger.error(f"Error getting installed apps for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "get_installed_apps"),
+            },
+            status_code=500,
+        )
+
+
+async def list_webhooks(request: Request) -> JSONResponse:
+    """GET /api/v1/webhooks - List all registered webhooks.
+
+    Returns list of webhook registrations for the authenticated user.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "list_webhooks"),
+            },
+            status_code=401,
+        )
+
+    try:
+        from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with httpx.AsyncClient(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Use WebhooksClient to list webhooks
+            webhooks_client = WebhooksClient(client, user_id)
+            webhooks = await webhooks_client.list_webhooks()
+
+            return JSONResponse({"webhooks": webhooks})
+
+    except Exception as e:
+        logger.error(f"Error listing webhooks for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "list_webhooks"),
+            },
+            status_code=500,
+        )
+
+
+async def create_webhook(request: Request) -> JSONResponse:
+    """POST /api/v1/webhooks - Create a new webhook registration.
+
+    Request body:
+    {
+        "event": "OCP\\Files\\Events\\Node\\NodeCreatedEvent",
+        "uri": "http://mcp:8000/webhooks/nextcloud",
+        "eventFilter": {"event.node.path": "/^\\/.*\\/files\\/Notes\\//"}
+    }
+
+    Returns the created webhook data including the webhook ID.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "create_webhook"),
+            },
+            status_code=401,
+        )
+
+    try:
+        from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+        # Parse request body
+        body = await request.json()
+        event = body.get("event")
+        uri = body.get("uri")
+        # Accept both camelCase (eventFilter) and snake_case (event_filter)
+        event_filter = body.get("eventFilter") or body.get("event_filter")
+
+        if not event or not uri:
+            return JSONResponse(
+                {
+                    "error": "Bad request",
+                    "message": "Missing required fields: event, uri",
+                },
+                status_code=400,
+            )
+
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with httpx.AsyncClient(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Use WebhooksClient to create webhook
+            webhooks_client = WebhooksClient(client, user_id)
+            webhook_data = await webhooks_client.create_webhook(
+                event=event, uri=uri, event_filter=event_filter
+            )
+
+            return JSONResponse({"webhook": webhook_data})
+
+    except Exception as e:
+        logger.error(f"Error creating webhook for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "create_webhook"),
+            },
+            status_code=500,
+        )
+
+
+async def delete_webhook(request: Request) -> JSONResponse:
+    """DELETE /api/v1/webhooks/{webhook_id} - Delete a webhook registration.
+
+    Returns success/failure status.
+
+    Requires OAuth bearer token for authentication.
+    """
+    try:
+        # Validate OAuth token and extract user
+        user_id, validated = await validate_token_and_get_user(request)
+    except Exception as e:
+        logger.warning(f"Unauthorized access to /api/v1/webhooks: {e}")
+        return JSONResponse(
+            {
+                "error": "Unauthorized",
+                "message": _sanitize_error_for_client(e, "delete_webhook"),
+            },
+            status_code=401,
+        )
+
+    try:
+        from nextcloud_mcp_server.client.webhooks import WebhooksClient
+
+        # Get webhook_id from path parameter
+        webhook_id = request.path_params.get("webhook_id")
+        if not webhook_id:
+            return JSONResponse(
+                {"error": "Bad request", "message": "Missing webhook_id"},
+                status_code=400,
+            )
+
+        try:
+            webhook_id = int(webhook_id)
+        except ValueError:
+            return JSONResponse(
+                {"error": "Bad request", "message": "Invalid webhook_id"},
+                status_code=400,
+            )
+
+        # Get Bearer token from request
+        token = extract_bearer_token(request)
+        if not token:
+            raise ValueError("Missing Authorization header")
+
+        # Get Nextcloud host from OAuth context
+        oauth_ctx = request.app.state.oauth_context
+        nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+        if not nextcloud_host:
+            raise ValueError("Nextcloud host not configured")
+
+        # Create authenticated HTTP client
+        async with httpx.AsyncClient(
+            base_url=nextcloud_host,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=30.0,
+        ) as client:
+            # Use WebhooksClient to delete webhook
+            webhooks_client = WebhooksClient(client, user_id)
+            await webhooks_client.delete_webhook(webhook_id=webhook_id)
+
+            return JSONResponse({"success": True, "message": "Webhook deleted"})
+
+    except Exception as e:
+        logger.error(f"Error deleting webhook for user {user_id}: {e}")
+        return JSONResponse(
+            {
+                "error": "Internal error",
+                "message": _sanitize_error_for_client(e, "delete_webhook"),
+            },
+            status_code=500,
+        )

nextcloud_mcp_server/auth/astrolabe_client.py

@@ -0,0 +1,152 @@
+"""
+Client for querying Astrolabe Management API for background sync credentials.
+
+This client uses OAuth client credentials flow to authenticate to Nextcloud
+and retrieve user app passwords for background sync operations.
+"""
+
+import logging
+import time
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class AstrolabeClient:
+    """Client for querying Astrolabe API for background sync credentials.
+
+    Uses OAuth client credentials flow to authenticate as the MCP server
+    and retrieve user app passwords that are stored in Nextcloud.
+    """
+
+    def __init__(
+        self,
+        nextcloud_host: str,
+        client_id: str,
+        client_secret: str,
+    ):
+        """
+        Initialize Astrolabe client.
+
+        Args:
+            nextcloud_host: Nextcloud base URL (e.g., https://cloud.example.com)
+            client_id: OAuth client ID for MCP server
+            client_secret: OAuth client secret
+        """
+        self.nextcloud_host = nextcloud_host.rstrip("/")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._token_cache: Optional[dict] = None  # {access_token, expires_at}
+
+    async def get_access_token(self) -> str:
+        """
+        Get access token using OAuth client credentials flow.
+
+        Tokens are cached with 1-minute early refresh to avoid expiration.
+
+        Returns:
+            Access token string
+
+        Raises:
+            httpx.HTTPError: If token request fails
+        """
+        # Check cache
+        if self._token_cache and time.time() < self._token_cache["expires_at"]:
+            logger.debug("Using cached OAuth token for Astrolabe API")
+            return self._token_cache["access_token"]
+
+        # Discover token endpoint
+        discovery_url = f"{self.nextcloud_host}/.well-known/openid-configuration"
+
+        async with httpx.AsyncClient() as client:
+            logger.debug(f"Discovering token endpoint from {discovery_url}")
+            discovery_resp = await client.get(discovery_url)
+            discovery_resp.raise_for_status()
+            token_endpoint = discovery_resp.json()["token_endpoint"]
+
+            logger.debug(f"Requesting client credentials token from {token_endpoint}")
+
+            # Request token using client credentials grant
+            token_resp = await client.post(
+                token_endpoint,
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                    "scope": "openid",  # Minimal scope
+                },
+            )
+            token_resp.raise_for_status()
+            data = token_resp.json()
+
+            # Cache with 1-minute early refresh
+            expires_in = data.get("expires_in", 3600)
+            self._token_cache = {
+                "access_token": data["access_token"],
+                "expires_at": time.time() + expires_in - 60,
+            }
+
+            logger.info(f"Obtained Astrolabe API token (expires in {expires_in}s)")
+            return data["access_token"]
+
+    async def get_user_app_password(self, user_id: str) -> Optional[str]:
+        """
+        Retrieve user's app password for background sync.
+
+        Args:
+            user_id: Nextcloud user ID
+
+        Returns:
+            App password string, or None if user hasn't provisioned
+
+        Raises:
+            httpx.HTTPError: If API request fails (except 404)
+        """
+        token = await self.get_access_token()
+        url = f"{self.nextcloud_host}/apps/astrolabe/api/v1/background-sync/credentials/{user_id}"
+
+        async with httpx.AsyncClient() as client:
+            logger.debug(f"Retrieving app password for user: {user_id}")
+
+            response = await client.get(
+                url,
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=10.0,
+            )
+
+            if response.status_code == 404:
+                logger.debug(f"No app password configured for user: {user_id}")
+                return None
+
+            response.raise_for_status()
+            data = response.json()
+
+            logger.info(
+                f"Retrieved app password for user: {user_id} (type: {data.get('credential_type')})"
+            )
+            return data.get("app_password")
+
+    async def get_background_sync_status(self, user_id: str) -> dict:
+        """
+        Get background sync status for a user.
+
+        Args:
+            user_id: Nextcloud user ID
+
+        Returns:
+            Dict with keys: has_access, credential_type, provisioned_at
+
+        Raises:
+            httpx.HTTPError: If API request fails
+        """
+        # For now, check if app password exists
+        # In the future, this could query a dedicated status endpoint
+        app_password = await self.get_user_app_password(user_id)
+
+        return {
+            "has_access": app_password is not None,
+            "credential_type": "app_password" if app_password else None,
+            "provisioned_at": None,  # TODO: Get from API if available
+        }

nextcloud_mcp_server/auth/browser_oauth_routes.py

@@ -8,6 +8,7 @@ import hashlib
 import logging
 import os
 import secrets
+import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode
 
@@ -301,25 +302,6 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
                 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,
@@ -400,8 +382,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})"

nextcloud_mcp_server/auth/keycloak_oauth.py

@@ -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
@@ -155,7 +156,6 @@ class KeycloakOAuthClient:
         Returns:
             Tuple of (code_verifier, code_challenge)
         """
-        import base64
 
         # Generate code verifier (43-128 characters)
         code_verifier = secrets.token_urlsafe(32)

nextcloud_mcp_server/auth/oauth_routes.py

@@ -23,6 +23,7 @@ import hashlib
 import logging
 import os
 import secrets
+import time
 from base64 import urlsafe_b64encode
 from urllib.parse import urlencode
 
@@ -521,8 +522,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}")

nextcloud_mcp_server/auth/provisioning_decorator.py

@@ -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")

nextcloud_mcp_server/auth/scope_authorization.py

@@ -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:

nextcloud_mcp_server/auth/storage.py

@@ -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:
     """

nextcloud_mcp_server/auth/token_broker.py

@@ -168,37 +168,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 +376,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 +446,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()
 

nextcloud_mcp_server/auth/unified_verifier.py

@@ -117,6 +117,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 +251,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 +367,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 +388,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 +495,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 +537,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,

nextcloud_mcp_server/auth/userinfo_routes.py

@@ -9,6 +9,7 @@ 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
 
@@ -19,6 +20,7 @@ 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
 
 logger = logging.getLogger(__name__)
 
@@ -105,9 +107,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 +128,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
@@ -385,8 +385,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 +633,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")

nextcloud_mcp_server/auth/viz_routes.py

@@ -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={

nextcloud_mcp_server/client/deck.py

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

nextcloud_mcp_server/config.py

@@ -1,6 +1,7 @@
 import logging
 import logging.config
 import os
+import socket
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Optional
@@ -163,6 +164,12 @@ def get_document_processor_config() -> dict[str, Any]:
 class Settings:
     """Application settings from environment variables."""
 
+    # Deployment mode (ADR-021: explicit mode selection)
+    # Optional: If not set, mode is auto-detected from other settings
+    # Valid values: single_user_basic, multi_user_basic, oauth_single_audience,
+    #               oauth_token_exchange, smithery
+    deployment_mode: Optional[str] = None
+
     # OAuth/OIDC settings
     oidc_discovery_url: Optional[str] = None
     oidc_client_id: Optional[str] = None
@@ -187,6 +194,11 @@ class Settings:
     enable_token_exchange: bool = False
     enable_offline_access: bool = False
 
+    # Multi-user BasicAuth pass-through mode (ADR-019 interim solution)
+    # When enabled, MCP server extracts BasicAuth credentials from request headers
+    # and passes them through to Nextcloud APIs (no storage, stateless)
+    enable_multi_user_basic_auth: bool = False
+
     # Token exchange cache settings
     token_exchange_cache_ttl: int = 300  # seconds (5 minutes default)
 
@@ -326,7 +338,6 @@ class Settings:
         Returns:
             Collection name string
         """
-        import socket
 
         # Use explicit override if user configured non-default value
         if self.qdrant_collection != "nextcloud_content":
@@ -345,6 +356,131 @@ 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.
+
+    Supports:
+    - ENABLE_SEMANTIC_SEARCH (new, preferred)
+    - VECTOR_SYNC_ENABLED (old, deprecated)
+
+    Returns:
+        True if semantic search should be enabled
+    """
+    logger = logging.getLogger(__name__)
+
+    new_value = os.getenv("ENABLE_SEMANTIC_SEARCH", "").lower() == "true"
+    old_value = os.getenv("VECTOR_SYNC_ENABLED", "").lower() == "true"
+
+    if new_value and old_value:
+        logger.warning(
+            "Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. "
+            "Using ENABLE_SEMANTIC_SEARCH. "
+            "VECTOR_SYNC_ENABLED is deprecated and will be removed in v1.0.0."
+        )
+    elif old_value and not new_value:
+        logger.warning(
+            "VECTOR_SYNC_ENABLED is deprecated. "
+            "Please use ENABLE_SEMANTIC_SEARCH instead. "
+            "Support for VECTOR_SYNC_ENABLED will be removed in v1.0.0."
+        )
+
+    return new_value or old_value
+
+
+def _is_multi_user_mode() -> bool:
+    """Detect if this is a multi-user deployment mode.
+
+    Multi-user modes are:
+    - Multi-user BasicAuth (ENABLE_MULTI_USER_BASIC_AUTH=true)
+    - OAuth Single-Audience (no username/password set)
+    - OAuth Token Exchange (ENABLE_TOKEN_EXCHANGE=true)
+
+    Single-user modes are:
+    - Single-user BasicAuth (username and password both set)
+    - Smithery Stateless (SMITHERY_DEPLOYMENT=true)
+
+    Returns:
+        True if multi-user mode detected
+    """
+    # Smithery is always single-user (stateless)
+    if os.getenv("SMITHERY_DEPLOYMENT", "false").lower() == "true":
+        return False
+
+    # Multi-user BasicAuth explicitly enabled
+    if os.getenv("ENABLE_MULTI_USER_BASIC_AUTH", "false").lower() == "true":
+        return True
+
+    # Token exchange implies OAuth multi-user
+    if os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true":
+        return True
+
+    # If both username and password are set, it's single-user BasicAuth
+    has_username = bool(os.getenv("NEXTCLOUD_USERNAME"))
+    has_password = bool(os.getenv("NEXTCLOUD_PASSWORD"))
+    if has_username and has_password:
+        return False
+
+    # Otherwise, assume OAuth multi-user (default when no credentials provided)
+    return True
+
+
+def _get_background_operations_enabled() -> bool:
+    """Get background operations enabled status with auto-enablement for semantic search.
+
+    Supports:
+    - ENABLE_BACKGROUND_OPERATIONS (new, preferred)
+    - ENABLE_OFFLINE_ACCESS (old, deprecated)
+    - Auto-enabled if ENABLE_SEMANTIC_SEARCH=true in multi-user modes
+
+    Returns:
+        True if background operations should be enabled
+    """
+    logger = logging.getLogger(__name__)
+
+    # Check new and old variable names
+    explicit = os.getenv("ENABLE_BACKGROUND_OPERATIONS", "").lower() == "true"
+    legacy = os.getenv("ENABLE_OFFLINE_ACCESS", "").lower() == "true"
+
+    if explicit and legacy:
+        logger.warning(
+            "Both ENABLE_BACKGROUND_OPERATIONS and ENABLE_OFFLINE_ACCESS are set. "
+            "Using ENABLE_BACKGROUND_OPERATIONS. "
+            "ENABLE_OFFLINE_ACCESS is deprecated and will be removed in v1.0.0."
+        )
+    elif legacy and not explicit:
+        logger.warning(
+            "ENABLE_OFFLINE_ACCESS is deprecated. "
+            "Please use ENABLE_BACKGROUND_OPERATIONS instead. "
+            "Support for ENABLE_OFFLINE_ACCESS will be removed in v1.0.0."
+        )
+
+    # Auto-enable if semantic search is enabled in multi-user mode
+    semantic_search_enabled = _get_semantic_search_enabled()
+    is_multi_user = _is_multi_user_mode()
+    auto_enabled = semantic_search_enabled and is_multi_user
+
+    if auto_enabled and not (explicit or legacy):
+        logger.info(
+            "Automatically enabled background operations for semantic search in multi-user mode. "
+            "Set ENABLE_BACKGROUND_OPERATIONS=false to disable (this will also disable semantic search)."
+        )
+
+    return explicit or legacy or auto_enabled
+
 
 def get_settings() -> Settings:
     """Get application settings from environment variables.
@@ -352,7 +488,13 @@ def get_settings() -> Settings:
     Returns:
         Settings object with configuration values
     """
+    # Get consolidated values with smart dependency resolution
+    enable_semantic_search = _get_semantic_search_enabled()
+    enable_background_operations = _get_background_operations_enabled()
+
     return Settings(
+        # Deployment mode (ADR-021)
+        deployment_mode=os.getenv("MCP_DEPLOYMENT_MODE"),
         # OAuth/OIDC settings
         oidc_discovery_url=os.getenv("OIDC_DISCOVERY_URL"),
         oidc_client_id=os.getenv("NEXTCLOUD_OIDC_CLIENT_ID"),
@@ -373,8 +515,10 @@ def get_settings() -> Settings:
         enable_token_exchange=(
             os.getenv("ENABLE_TOKEN_EXCHANGE", "false").lower() == "true"
         ),
-        enable_offline_access=(
-            os.getenv("ENABLE_OFFLINE_ACCESS", "false").lower() == "true"
+        enable_offline_access=enable_background_operations,  # Smart dependency resolution
+        # Multi-user BasicAuth pass-through mode
+        enable_multi_user_basic_auth=(
+            os.getenv("ENABLE_MULTI_USER_BASIC_AUTH", "false").lower() == "true"
         ),
         # Token exchange cache settings
         token_exchange_cache_ttl=int(os.getenv("TOKEN_EXCHANGE_CACHE_TTL", "300")),
@@ -382,9 +526,7 @@ def get_settings() -> Settings:
         token_encryption_key=os.getenv("TOKEN_ENCRYPTION_KEY"),
         token_storage_db=os.getenv("TOKEN_STORAGE_DB", "/tmp/tokens.db"),
         # Vector sync settings (ADR-007)
-        vector_sync_enabled=(
-            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
-        ),
+        vector_sync_enabled=enable_semantic_search,  # Smart dependency resolution
         vector_sync_scan_interval=int(os.getenv("VECTOR_SYNC_SCAN_INTERVAL", "300")),
         vector_sync_processor_workers=int(
             os.getenv("VECTOR_SYNC_PROCESSOR_WORKERS", "3")

nextcloud_mcp_server/config_validators.py

@@ -0,0 +1,459 @@
+"""Configuration validation and mode detection for the MCP server.
+
+This module provides:
+- Mode detection based on configuration
+- Configuration validation with clear error messages
+- Single source of truth for deployment mode requirements
+
+See ADR-020 for detailed architecture and deployment mode documentation.
+"""
+
+import logging
+import os
+from dataclasses import dataclass
+from enum import Enum
+
+from nextcloud_mcp_server.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class AuthMode(Enum):
+    """Authentication mode for the MCP server.
+
+    Determines how users authenticate and how the server accesses Nextcloud.
+    """
+
+    SINGLE_USER_BASIC = "single_user_basic"
+    MULTI_USER_BASIC = "multi_user_basic"
+    OAUTH_SINGLE_AUDIENCE = "oauth_single"
+    OAUTH_TOKEN_EXCHANGE = "oauth_exchange"
+    SMITHERY_STATELESS = "smithery"
+
+
+@dataclass
+class ModeRequirements:
+    """Requirements for a deployment mode.
+
+    Attributes:
+        required: Configuration variables that must be set
+        optional: Configuration variables that may be set
+        forbidden: Configuration variables that should not be set
+        conditional: Additional requirements based on feature flags
+                     Format: {feature_flag: [required_vars]}
+        description: Human-readable description of the mode
+    """
+
+    required: list[str]
+    optional: list[str]
+    forbidden: list[str]
+    conditional: dict[str, list[str]]
+    description: str
+
+
+# Mode requirements definition
+MODE_REQUIREMENTS: dict[AuthMode, ModeRequirements] = {
+    AuthMode.SINGLE_USER_BASIC: ModeRequirements(
+        required=["nextcloud_host", "nextcloud_username", "nextcloud_password"],
+        optional=[
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+            "document_chunk_size",
+            "document_chunk_overlap",
+        ],
+        forbidden=[
+            "enable_multi_user_basic_auth",
+            "enable_token_exchange",
+            "oidc_client_id",
+            "oidc_client_secret",
+        ],
+        conditional={
+            "vector_sync_enabled": [
+                # Either qdrant_url OR qdrant_location (checked in Settings.__post_init__)
+                # At least one embedding provider (ollama_base_url OR openai_api_key)
+            ],
+        },
+        description="Single-user deployment with BasicAuth credentials. "
+        "Suitable for personal Nextcloud instances and local development.",
+    ),
+    AuthMode.MULTI_USER_BASIC: ModeRequirements(
+        required=["nextcloud_host", "enable_multi_user_basic_auth"],
+        optional=[
+            # Background sync with app passwords (via Astrolabe)
+            "enable_offline_access",
+            "token_encryption_key",
+            "token_storage_db",
+            "oidc_client_id",
+            "oidc_client_secret",
+            # Vector sync
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+        ],
+        forbidden=[
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_token_exchange",
+        ],
+        conditional={
+            "enable_offline_access": [
+                # OAuth credentials validated separately (lines 397-406) with clearer error message
+                "token_encryption_key",
+                "token_storage_db",
+            ],
+            # Note: vector_sync_enabled (now ENABLE_SEMANTIC_SEARCH) automatically
+            # enables background operations in multi-user modes. No explicit
+            # enable_offline_access setting required.
+        },
+        description="Multi-user deployment with BasicAuth pass-through. "
+        "Users provide credentials in request headers. "
+        "Optional background sync using app passwords stored via Astrolabe.",
+    ),
+    AuthMode.OAUTH_SINGLE_AUDIENCE: ModeRequirements(
+        required=["nextcloud_host"],
+        optional=[
+            # OAuth credentials (uses DCR if not provided)
+            "oidc_client_id",
+            "oidc_client_secret",
+            "oidc_discovery_url",
+            # Offline access
+            "enable_offline_access",
+            "token_encryption_key",
+            "token_storage_db",
+            # Vector sync
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+            # Scopes
+            "nextcloud_oidc_scopes",
+        ],
+        forbidden=[
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_token_exchange",
+            "enable_multi_user_basic_auth",
+        ],
+        conditional={
+            "enable_offline_access": [
+                "token_encryption_key",
+                "token_storage_db",
+            ],
+            # Note: vector_sync_enabled (now ENABLE_SEMANTIC_SEARCH) automatically
+            # enables background operations in multi-user modes. No explicit
+            # enable_offline_access setting required.
+        },
+        description="OAuth multi-user deployment with single-audience tokens. "
+        "Tokens work for both MCP server and Nextcloud APIs (pass-through). "
+        "Uses Dynamic Client Registration if credentials not provided.",
+    ),
+    AuthMode.OAUTH_TOKEN_EXCHANGE: ModeRequirements(
+        required=["nextcloud_host", "enable_token_exchange"],
+        optional=[
+            # OAuth credentials
+            "oidc_client_id",
+            "oidc_client_secret",
+            "oidc_discovery_url",
+            # Token exchange settings
+            "token_exchange_cache_ttl",
+            # Offline access
+            "enable_offline_access",
+            "token_encryption_key",
+            "token_storage_db",
+            # Vector sync
+            "vector_sync_enabled",
+            "qdrant_url",
+            "qdrant_location",
+            "ollama_base_url",
+            "ollama_embedding_model",
+            "openai_api_key",
+            "openai_embedding_model",
+        ],
+        forbidden=[
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_multi_user_basic_auth",
+        ],
+        conditional={
+            "enable_offline_access": [
+                "token_encryption_key",
+                "token_storage_db",
+            ],
+            # Note: vector_sync_enabled (now ENABLE_SEMANTIC_SEARCH) automatically
+            # enables background operations in multi-user modes. No explicit
+            # enable_offline_access setting required.
+        },
+        description="OAuth multi-user deployment with token exchange (RFC 8693). "
+        "MCP tokens are separate from Nextcloud tokens. "
+        "Server exchanges MCP token for Nextcloud token on each request.",
+    ),
+    AuthMode.SMITHERY_STATELESS: ModeRequirements(
+        required=[],  # All config from session URL params
+        optional=[],
+        forbidden=[
+            "nextcloud_host",
+            "nextcloud_username",
+            "nextcloud_password",
+            "enable_multi_user_basic_auth",
+            "enable_token_exchange",
+            "enable_offline_access",
+            "vector_sync_enabled",
+            "oidc_client_id",
+            "oidc_client_secret",
+        ],
+        conditional={},
+        description="Stateless multi-tenant deployment for Smithery platform. "
+        "Configuration comes from session URL parameters. "
+        "No persistent storage, no OAuth, no vector sync.",
+    ),
+}
+
+
+def detect_auth_mode(settings: Settings) -> AuthMode:
+    """Detect authentication mode from configuration.
+
+    Mode detection priority (ADR-021):
+    0. Explicit MCP_DEPLOYMENT_MODE (if set) - NEW in ADR-021
+    1. Smithery (explicit flag)
+    2. Token exchange (most specific OAuth mode)
+    3. Multi-user BasicAuth
+    4. Single-user BasicAuth
+    5. OAuth single-audience (default OAuth mode)
+
+    Args:
+        settings: Application settings
+
+    Returns:
+        Detected AuthMode
+
+    Raises:
+        ValueError: If explicit deployment_mode is invalid or conflicts with detected mode
+    """
+
+    logger = logging.getLogger(__name__)
+
+    # ADR-021: Check for explicit deployment mode first
+    if settings.deployment_mode:
+        mode_str = settings.deployment_mode.lower().strip()
+
+        # Map string to AuthMode enum
+        mode_map = {
+            "single_user_basic": AuthMode.SINGLE_USER_BASIC,
+            "multi_user_basic": AuthMode.MULTI_USER_BASIC,
+            "oauth_single_audience": AuthMode.OAUTH_SINGLE_AUDIENCE,
+            "oauth_token_exchange": AuthMode.OAUTH_TOKEN_EXCHANGE,
+            "smithery": AuthMode.SMITHERY_STATELESS,
+        }
+
+        if mode_str not in mode_map:
+            valid_modes = ", ".join(mode_map.keys())
+            raise ValueError(
+                f"Invalid MCP_DEPLOYMENT_MODE: '{settings.deployment_mode}'. "
+                f"Valid values: {valid_modes}"
+            )
+
+        explicit_mode = mode_map[mode_str]
+        logger.info(f"Using explicit deployment mode: {explicit_mode.value}")
+        return explicit_mode
+
+    # Auto-detection (existing behavior)
+    # Check for Smithery mode (explicit environment variable)
+    # Note: This checks the environment directly, not settings
+    # because Smithery mode has no settings-based config
+    if os.getenv("SMITHERY_DEPLOYMENT", "false").lower() == "true":
+        return AuthMode.SMITHERY_STATELESS
+
+    # Check for token exchange (most specific OAuth mode)
+    if settings.enable_token_exchange:
+        return AuthMode.OAUTH_TOKEN_EXCHANGE
+
+    # Check for multi-user BasicAuth
+    if settings.enable_multi_user_basic_auth:
+        return AuthMode.MULTI_USER_BASIC
+
+    # Check for single-user BasicAuth (explicit credentials)
+    if settings.nextcloud_username and settings.nextcloud_password:
+        return AuthMode.SINGLE_USER_BASIC
+
+    # Default: OAuth single-audience mode
+    # This is the safest multi-user mode (no credential storage)
+    return AuthMode.OAUTH_SINGLE_AUDIENCE
+
+
+def validate_configuration(settings: Settings) -> tuple[AuthMode, list[str]]:
+    """Validate configuration for detected mode.
+
+    Args:
+        settings: Application settings
+
+    Returns:
+        Tuple of (detected_mode, list_of_errors)
+        Empty list means valid configuration.
+    """
+    mode = detect_auth_mode(settings)
+    requirements = MODE_REQUIREMENTS[mode]
+    errors: list[str] = []
+
+    logger.debug(f"Validating configuration for mode: {mode.value}")
+
+    # Check required variables
+    for var in requirements.required:
+        value = getattr(settings, var, None)
+        if value is None or (isinstance(value, str) and not value.strip()):
+            errors.append(
+                f"[{mode.value}] Missing required configuration: {var.upper()}"
+            )
+
+    # Check forbidden variables
+    for var in requirements.forbidden:
+        value = getattr(settings, var, None)
+        # For bools, check if True (forbidden means must be False/unset)
+        # For strings, check if non-empty
+        is_set = False
+        if isinstance(value, bool):
+            is_set = value is True
+        elif isinstance(value, str):
+            is_set = bool(value.strip())
+        elif value is not None:
+            is_set = True
+
+        if is_set:
+            errors.append(
+                f"[{mode.value}] Forbidden configuration: {var.upper()} "
+                f"should not be set in this mode"
+            )
+
+    # Check conditional requirements
+    for condition, required_vars in requirements.conditional.items():
+        # Check if the condition is enabled
+        condition_value = getattr(settings, condition, None)
+        is_enabled = False
+
+        if isinstance(condition_value, bool):
+            is_enabled = condition_value is True
+        elif isinstance(condition_value, str):
+            is_enabled = bool(condition_value.strip())
+        elif condition_value is not None:
+            is_enabled = True
+
+        if is_enabled:
+            # Check that all required vars for this condition are set
+            for var in required_vars:
+                value = getattr(settings, var, None)
+
+                # For boolean requirements, check that they are True (not just set)
+                if hasattr(Settings, var):
+                    field_type = type(getattr(Settings(), var, None))
+                    if field_type is bool:
+                        if value is not True:
+                            errors.append(
+                                f"[{mode.value}] {var.upper()} must be enabled when "
+                                f"{condition.upper()} is enabled"
+                            )
+                        continue
+
+                # For non-boolean requirements, check that they are set
+                if value is None or (isinstance(value, str) and not value.strip()):
+                    errors.append(
+                        f"[{mode.value}] {var.upper()} is required when "
+                        f"{condition.upper()} is enabled"
+                    )
+
+    # Special validations for specific modes
+    if mode == AuthMode.SINGLE_USER_BASIC:
+        # Validate that NEXTCLOUD_HOST doesn't have trailing slash
+        if settings.nextcloud_host and settings.nextcloud_host.endswith("/"):
+            errors.append(
+                f"[{mode.value}] NEXTCLOUD_HOST should not have trailing slash: "
+                f"{settings.nextcloud_host}"
+            )
+
+    if mode in [
+        AuthMode.OAUTH_SINGLE_AUDIENCE,
+        AuthMode.OAUTH_TOKEN_EXCHANGE,
+    ]:
+        # If OAuth credentials not provided, DCR must be available
+        # (This is a runtime check, not a config check, so we just warn)
+        if not settings.oidc_client_id or not settings.oidc_client_secret:
+            logger.info(
+                f"[{mode.value}] OAuth credentials not configured. "
+                "Will attempt Dynamic Client Registration (DCR) at startup."
+            )
+
+    if mode == AuthMode.MULTI_USER_BASIC:
+        # If background operations enabled, check for OAuth credentials (for app password retrieval)
+        # Allow DCR as fallback, just like OAuth modes
+        if settings.enable_offline_access:
+            if not settings.oidc_client_id or not settings.oidc_client_secret:
+                logger.info(
+                    f"[{mode.value}] OAuth credentials not configured. "
+                    "Will attempt Dynamic Client Registration (DCR) at startup "
+                    "(required for app password retrieval via Astrolabe)."
+                )
+
+        # Note: Vector sync no longer requires explicit ENABLE_OFFLINE_ACCESS setting
+        # ENABLE_SEMANTIC_SEARCH (formerly VECTOR_SYNC_ENABLED) automatically enables
+        # background operations in multi-user modes via smart dependency resolution
+        # in config.py
+
+    # Note: Embedding provider validation removed - Simple provider is always
+    # available as fallback (ADR-015). Users can optionally configure Ollama or OpenAI
+    # for better quality embeddings.
+
+    return mode, errors
+
+
+def get_mode_summary(mode: AuthMode) -> str:
+    """Get human-readable summary of a deployment mode.
+
+    Args:
+        mode: Deployment mode
+
+    Returns:
+        Multi-line string describing the mode
+    """
+    requirements = MODE_REQUIREMENTS[mode]
+
+    summary_lines = [
+        f"Mode: {mode.value}",
+        f"Description: {requirements.description}",
+        "",
+        "Required configuration:",
+    ]
+
+    if requirements.required:
+        for var in requirements.required:
+            summary_lines.append(f"  - {var.upper()}")
+    else:
+        summary_lines.append("  (none - configured via session)")
+
+    summary_lines.append("")
+    summary_lines.append("Optional configuration:")
+
+    if requirements.optional:
+        for var in requirements.optional:
+            summary_lines.append(f"  - {var.upper()}")
+    else:
+        summary_lines.append("  (none)")
+
+    if requirements.conditional:
+        summary_lines.append("")
+        summary_lines.append("Conditional requirements:")
+        for condition, vars in requirements.conditional.items():
+            summary_lines.append(f"  When {condition.upper()} is enabled:")
+            for var in vars:
+                summary_lines.append(f"    - {var.upper()}")
+
+    return "\n".join(summary_lines)

nextcloud_mcp_server/context.py

@@ -67,6 +67,11 @@ async def get_client(ctx: Context) -> NextcloudClient:
         return _get_client_from_session_config(ctx)
 
     settings = get_settings()
+
+    # Multi-user BasicAuth pass-through mode - extract credentials from request
+    if settings.enable_multi_user_basic_auth:
+        return _get_client_from_basic_auth(ctx)
+
     lifespan_ctx = ctx.request_context.lifespan_context
 
     # BasicAuth mode - use shared client (no token exchange)
@@ -177,3 +182,67 @@ def _get_client_from_session_config(ctx: Context) -> NextcloudClient:
         username=username,
         auth=BasicAuth(username, app_password),
     )
+
+
+def _get_client_from_basic_auth(ctx: Context) -> NextcloudClient:
+    """
+    Create NextcloudClient from BasicAuth credentials in request headers.
+
+    For multi-user BasicAuth pass-through mode, this function extracts
+    username/password from the Authorization: Basic header (stored by
+    BasicAuthMiddleware) and creates a client that passes these credentials
+    through to Nextcloud APIs.
+
+    The credentials are NOT stored persistently - they exist only for the
+    duration of this request (stateless).
+
+    Args:
+        ctx: MCP request context with basic_auth in request state
+
+    Returns:
+        NextcloudClient configured with BasicAuth credentials
+
+    Raises:
+        ValueError: If BasicAuth credentials not found in request or if
+                   NEXTCLOUD_HOST is not configured
+    """
+    settings = get_settings()
+
+    # Validate that NEXTCLOUD_HOST is configured
+    if not settings.nextcloud_host:
+        raise ValueError(
+            "NEXTCLOUD_HOST environment variable must be set for multi-user BasicAuth mode"
+        )
+
+    # Extract BasicAuth credentials from request state (set by BasicAuthMiddleware)
+    # Access scope through the request object
+    scope = getattr(ctx.request_context.request, "scope", None)
+    if scope is None:
+        raise ValueError("Request scope not available in context")
+
+    request_state = scope.get("state", {})
+    basic_auth = request_state.get("basic_auth")
+
+    if not basic_auth:
+        raise ValueError(
+            "BasicAuth credentials not found in request. "
+            "Ensure Authorization: Basic header is provided with valid credentials."
+        )
+
+    username = basic_auth.get("username")
+    password = basic_auth.get("password")
+
+    if not username or not password:
+        raise ValueError("Invalid BasicAuth credentials - missing username or password")
+
+    logger.debug(
+        f"Creating multi-user BasicAuth client for {settings.nextcloud_host} as {username}"
+    )
+
+    # Create client that passes BasicAuth credentials through to Nextcloud
+    # settings.nextcloud_host is guaranteed to be str after the check above
+    return NextcloudClient(
+        base_url=settings.nextcloud_host,
+        username=username,
+        auth=BasicAuth(username, password),
+    )

nextcloud_mcp_server/document_processors/pymupdf.py

@@ -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:

nextcloud_mcp_server/embedding/bm25_provider.py

@@ -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]

nextcloud_mcp_server/migrations.py

@@ -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"

nextcloud_mcp_server/observability/metrics.py

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

nextcloud_mcp_server/search/algorithms.py

@@ -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()

nextcloud_mcp_server/search/context.py

@@ -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")

nextcloud_mcp_server/search/pdf_highlighter.py

@@ -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:

nextcloud_mcp_server/server/deck.py

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

nextcloud_mcp_server/server/oauth_tools.py

@@ -12,6 +12,7 @@ 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
@@ -53,8 +54,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}")
@@ -101,6 +100,9 @@ class ProvisioningStatus(BaseModel):
     provisioned_at: Optional[str] = Field(
         None, description="ISO timestamp when provisioned"
     )
+    credential_type: Optional[str] = Field(
+        None, description="Type of credential ('refresh_token' or 'app_password')"
+    )
     client_id: Optional[str] = Field(
         None, description="Client ID that initiated the original Flow 1"
     )
@@ -114,8 +116,8 @@ class ProvisioningResult(BaseModel):
     """Result of provisioning attempt."""
 
     success: bool = Field(description="Whether provisioning was initiated")
-    authorization_url: Optional[str] = Field(
-        None, description="URL for user to complete OAuth authorization"
+    provisioning_url: Optional[str] = Field(
+        None, description="URL to Astrolabe settings for provisioning background sync"
     )
     message: str = Field(description="Status message for the user")
     already_provisioned: bool = Field(
@@ -143,8 +145,9 @@ async def get_provisioning_status(ctx: Context, user_id: str) -> ProvisioningSta
     """
     Check the provisioning status for Nextcloud access.
 
-    This checks whether the user has completed Flow 2 to provision
-    offline access to Nextcloud resources.
+    Checks for both credential types:
+    1. App password from Astrolabe (works today)
+    2. OAuth refresh token from storage (for future)
 
     Args:
         mcp: MCP context
@@ -153,6 +156,37 @@ async def get_provisioning_status(ctx: Context, user_id: str) -> ProvisioningSta
     Returns:
         ProvisioningStatus with current provisioning state
     """
+    from datetime import datetime, timezone
+
+    from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+
+    # Check for app password first (interim solution)
+    if settings.oidc_client_id and settings.oidc_client_secret:
+        try:
+            astrolabe = AstrolabeClient(
+                nextcloud_host=settings.nextcloud_host or "",
+                client_id=settings.oidc_client_id,
+                client_secret=settings.oidc_client_secret,
+            )
+            status = await astrolabe.get_background_sync_status(user_id)
+
+            if status.get("has_access"):
+                logger.info(
+                    f"  get_provisioning_status: ✓ App password FOUND for user_id={user_id}"
+                )
+                provisioned_at_str = status.get("provisioned_at")
+                return ProvisioningStatus(
+                    is_provisioned=True,
+                    provisioned_at=provisioned_at_str,
+                    credential_type="app_password",
+                )
+        except Exception as e:
+            logger.debug(f"  App password check failed for {user_id}: {e}")
+
+    # Check for OAuth refresh token (fallback)
     logger.info(
         f"  get_provisioning_status: Looking up refresh token for user_id={user_id}"
     )
@@ -163,7 +197,7 @@ async def get_provisioning_status(ctx: Context, user_id: str) -> ProvisioningSta
 
     if not token_data:
         logger.info(
-            f"  get_provisioning_status: ✗ No refresh token found for user_id={user_id}"
+            f"  get_provisioning_status: ✗ No credentials found for user_id={user_id}"
         )
         return ProvisioningStatus(is_provisioned=False)
 
@@ -178,14 +212,13 @@ async def get_provisioning_status(ctx: Context, user_id: str) -> ProvisioningSta
     # Convert timestamp to ISO format if present
     provisioned_at_str = None
     if token_data.get("provisioned_at"):
-        from datetime import datetime, timezone
-
         dt = datetime.fromtimestamp(token_data["provisioned_at"], tz=timezone.utc)
         provisioned_at_str = dt.isoformat()
 
     return ProvisioningStatus(
         is_provisioned=True,
         provisioned_at=provisioned_at_str,
+        credential_type="refresh_token",
         client_id=token_data.get("provisioning_client_id"),
         scopes=token_data.get("scopes"),
         flow_type=token_data.get("flow_type", "hybrid"),
@@ -239,36 +272,22 @@ async def provision_nextcloud_access(
     """
     MCP Tool: Provision offline access to Nextcloud resources.
 
-    This tool initiates Flow 2 of the Progressive Consent architecture,
-    allowing the MCP server to obtain delegated access to Nextcloud APIs.
-
-    The user must complete the OAuth flow in their browser to grant access.
+    Returns URL to Astrolabe settings page where users can provision background
+    sync access using either:
+    - App password (works today, interim solution)
+    - OAuth refresh token (future, when Nextcloud supports OAuth for app APIs)
 
     Args:
         ctx: MCP context with user's Flow 1 token
         user_id: Optional user identifier (extracted from token if not provided)
 
     Returns:
-        ProvisioningResult with authorization URL or status
+        ProvisioningResult with Astrolabe settings URL or status
     """
     try:
         # Extract user ID from the MCP access token (Flow 1 token)
         if not user_id:
-            # Get the authorization token from context
-            if hasattr(ctx, "authorization") and ctx.authorization:
-                token = ctx.authorization.token  # type: ignore
-                # Decode token to get user info
-                try:
-                    import jwt
-
-                    payload = jwt.decode(token, options={"verify_signature": False})
-                    user_id = payload.get("sub", "unknown")
-                    logger.info(f"Extracted user_id from Flow 1 token: {user_id}")
-                except Exception as e:
-                    logger.warning(f"Failed to decode token: {e}")
-                    user_id = "default_user"
-            else:
-                user_id = "default_user"
+            user_id = await extract_user_id_from_token(ctx)
 
         # Check if already provisioned
         status = await get_provisioning_status(ctx, user_id)
@@ -277,101 +296,40 @@ async def provision_nextcloud_access(
                 success=True,
                 already_provisioned=True,
                 message=(
-                    f"Nextcloud access is already provisioned (since {status.provisioned_at}). "
+                    f"Nextcloud access is already provisioned (credential_type={status.credential_type}, "
+                    f"since {status.provisioned_at}). "
                     "Use 'revoke_nextcloud_access' if you want to re-provision."
                 ),
             )
 
-        # 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."
                 ),
             )
 
-        # Get MCP server's OAuth client credentials
-        # Try environment variable first, then fall back to DCR client_id
-        server_client_id = os.getenv("MCP_SERVER_CLIENT_ID")
-        if not server_client_id:
-            # Try to get from lifespan context (DCR)
-            lifespan_ctx = ctx.request_context.lifespan_context
-            if hasattr(lifespan_ctx, "server_client_id"):
-                server_client_id = lifespan_ctx.server_client_id
-
-        if not server_client_id:
-            return ProvisioningResult(
-                success=False,
-                message=(
-                    "MCP server OAuth client not configured. "
-                    "Set MCP_SERVER_CLIENT_ID environment variable or use Dynamic Client Registration."
-                ),
-            )
-
-        # Generate OAuth URL for Flow 2
-        oidc_discovery_url = os.getenv(
-            "OIDC_DISCOVERY_URL",
-            f"{os.getenv('NEXTCLOUD_HOST')}/.well-known/openid-configuration",
-        )
-
-        # Generate secure state for CSRF protection
-        state = secrets.token_urlsafe(32)
-
-        # Store state in session for validation on callback
-        storage = RefreshTokenStorage.from_env()
-        await storage.initialize()
-
-        # Create OAuth session for Flow 2
-        session_id = f"flow2_{user_id}_{secrets.token_hex(8)}"
-        redirect_uri = f"{os.getenv('NEXTCLOUD_MCP_SERVER_URL', 'http://localhost:8000')}/oauth/callback"
-
-        await storage.store_oauth_session(
-            session_id=session_id,
-            client_redirect_uri="",  # No client redirect for Flow 2
-            state=state,
-            flow_type="flow2",
-            is_provisioning=True,
-            ttl_seconds=600,  # 10 minute TTL
-        )
-
-        # Define scopes for Nextcloud access
-        scopes = [
-            "openid",
-            "profile",
-            "email",
-            "offline_access",  # Critical for background operations
-            "notes:read",
-            "notes:write",
-            "calendar:read",
-            "calendar:write",
-            "contacts:read",
-            "contacts:write",
-            "files:read",
-            "files:write",
-        ]
-
-        # Generate authorization URL
-        auth_url = generate_oauth_url_for_flow2(
-            oidc_discovery_url=oidc_discovery_url,
-            server_client_id=server_client_id,
-            redirect_uri=redirect_uri,
-            state=state,
-            scopes=scopes,
-        )
+        # Return Astrolabe settings URL for background sync provisioning
+        nextcloud_host = os.getenv("NEXTCLOUD_HOST", "http://localhost:8080")
+        astrolabe_url = f"{nextcloud_host}/settings/user/astrolabe#background-sync"
 
         return ProvisioningResult(
             success=True,
-            authorization_url=auth_url,
+            provisioning_url=astrolabe_url,
             message=(
-                "Please visit the authorization URL to grant the MCP server "
-                "offline access to your Nextcloud resources. This is a one-time "
-                "setup that allows the server to access Nextcloud on your behalf "
-                "even when you're not actively connected."
+                "Visit Astrolabe settings to provision background sync access.\n\n"
+                "You can choose either:\n"
+                "- App password (works today, recommended for now)\n"
+                "- OAuth refresh token (future, when Nextcloud fully supports OAuth)\n\n"
+                "After provisioning, background sync will enable the MCP server to "
+                "access Nextcloud resources even when you're not actively connected."
             ),
         )
 
@@ -530,13 +488,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

nextcloud_mcp_server/server/semantic.py

@@ -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,

nextcloud_mcp_server/server/webdav.py

@@ -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:

nextcloud_mcp_server/vector/document_chunker.py

@@ -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:

nextcloud_mcp_server/vector/html_processor.py

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

nextcloud_mcp_server/vector/oauth_sync.py

@@ -1,10 +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
+
+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
@@ -18,6 +31,7 @@ from anyio.streams.memory import (
     MemoryObjectReceiveStream,
     MemoryObjectSendStream,
 )
+from httpx import BasicAuth
 
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import get_settings
@@ -53,12 +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.
+
+    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
@@ -66,15 +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
     """
     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,
@@ -82,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()
@@ -113,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(
@@ -125,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:
@@ -143,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():
@@ -180,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
@@ -192,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
@@ -206,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(
@@ -226,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.
 
@@ -244,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
@@ -256,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(
@@ -316,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:
@@ -344,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")

nextcloud_mcp_server/vector/processor.py

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

nextcloud_mcp_server/vector/scanner.py

@@ -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(

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.56.2"
+version = "0.63.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"}
@@ -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"
@@ -114,7 +114,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]

scripts/bump-astrolabe.sh

@@ -58,6 +58,15 @@ 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

scripts/bump-helm.sh

@@ -53,6 +53,15 @@ 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

scripts/bump-mcp.sh

@@ -44,6 +44,14 @@ fi
 
 # Run commitizen bump and capture output
 if ! output=$($CZ_CMD 2>&1); then
+    # 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

scripts/dbquery.py

@@ -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())

scripts/sqlitequery.py

@@ -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())

tests/client/conftest.py

@@ -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:

tests/client/deck/test_deck_update_card_api.py

@@ -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"

tests/conftest.py

@@ -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
@@ -114,6 +124,7 @@ async def create_mcp_client_session(
     client_name: str = "MCP",
     elicitation_callback: Any = None,
     sampling_callback: Any = None,
+    headers: dict[str, str] | None = None,
 ) -> AsyncGenerator[ClientSession, Any]:
     """
     Factory function to create an MCP client session with proper lifecycle management.
@@ -135,6 +146,8 @@ async def create_mcp_client_session(
             Should match signature: async def callback(context: RequestContext, params: ElicitRequestParams) -> ElicitResult | ErrorData
         sampling_callback: Optional callback for handling sampling (LLM generation) requests.
             Should match signature: async def callback(context: RequestContext, params: CreateMessageRequestParams) -> CreateMessageResult | ErrorData
+        headers: Optional custom headers (e.g., for BasicAuth). If both headers and token are provided,
+            custom headers take precedence.
 
     Yields:
         Initialized MCP ClientSession
@@ -147,8 +160,9 @@ async def create_mcp_client_session(
     """
     logger.info(f"Creating Streamable HTTP client for {client_name}")
 
-    # Prepare headers with OAuth token if provided
-    headers = {"Authorization": f"Bearer {token}"} if token else None
+    # Prepare headers - custom headers take precedence over token-based auth
+    if headers is None:
+        headers = {"Authorization": f"Bearer {token}"} if token else None
 
     # Use native async with - Python ensures LIFO cleanup
     # Cleanup order will be: ClientSession.__aexit__ -> streamablehttp_client.__aexit__
@@ -240,6 +254,31 @@ async def nc_mcp_oauth_client(
         yield session
 
 
+@pytest.fixture(scope="session")
+async def nc_mcp_basic_auth_client(
+    anyio_backend,
+) -> AsyncGenerator[ClientSession, Any]:
+    """
+    Fixture to create an MCP client session with BasicAuth credentials.
+    Connects to the multi-user BasicAuth MCP server on port 8003 with ENABLE_MULTI_USER_BASIC_AUTH=true.
+
+    Uses BasicAuth credentials for multi-user pass-through mode (ADR-020).
+    Credentials are passed in Authorization header and forwarded to Nextcloud APIs.
+
+    Uses anyio pytest plugin for proper async fixture handling.
+    """
+
+    credentials = base64.b64encode(b"admin:admin").decode("utf-8")
+    auth_header = f"Basic {credentials}"
+
+    async for session in create_mcp_client_session(
+        url="http://localhost:8003/mcp",
+        headers={"Authorization": auth_header},
+        client_name="BasicAuth MCP (Multi-User)",
+    ):
+        yield session
+
+
 @pytest.fixture(scope="session")
 async def nc_mcp_oauth_jwt_client(
     anyio_backend,
@@ -312,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)
@@ -1078,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 = {}
@@ -1728,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")
@@ -2017,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")
@@ -2290,7 +2318,10 @@ async def test_users_setup(anyio_backend, nc_client: NextcloudClient):
         },
     }
 
-    logger.info("Creating test users for multi-user OAuth testing...")
+    logger.info("=" * 60)
+    logger.info("EXECUTING test_users_setup FIXTURE (session-scoped)")
+    logger.info(f"Creating test users: {list(test_user_configs.keys())}")
+    logger.info("=" * 60)
     created_users = []
 
     try:
@@ -2320,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
@@ -2384,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")
 
@@ -2527,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
@@ -2678,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]}"
@@ -2714,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]}"
@@ -2849,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
@@ -3187,3 +3216,238 @@ async def nc_mcp_keycloak_client_no_custom_scopes(
         client_name="Keycloak No Custom Scopes MCP",
     ):
         yield session
+
+
+# ========================================================================
+# Astrolabe Dynamic Configuration Fixtures
+# ========================================================================
+
+
+@pytest.fixture(scope="session")
+async def configure_astrolabe_for_mcp_server(nc_client):
+    """Configure Astrolabe app to connect to a specific MCP server.
+
+    This fixture dynamically configures the Astrolabe app's MCP server settings
+    and OAuth client, allowing tests to verify integration with different MCP
+    server deployments (mcp-oauth, mcp-keycloak, mcp-multi-user-basic, etc.).
+
+    Usage:
+        async def test_my_integration(configure_astrolabe_for_mcp_server):
+            await configure_astrolabe_for_mcp_server(
+                mcp_server_internal_url="http://mcp-oauth:8001",
+                mcp_server_public_url="http://localhost:8001"
+            )
+            # ... test Astrolabe integration ...
+
+    Args:
+        nc_client: NextcloudClient fixture for occ command execution
+
+    Returns:
+        Async function that accepts:
+            - mcp_server_internal_url: Internal Docker URL for PHP app to call MCP APIs
+            - mcp_server_public_url: Public URL for OAuth token audience validation
+            - client_id: Optional OAuth client ID (default: "nextcloudMcpServerUIPublicClient")
+    """
+
+    async def _configure(
+        mcp_server_internal_url: str,
+        mcp_server_public_url: str,
+        client_id: str = "nextcloudMcpServerUIPublicClient",
+    ) -> dict[str, str]:
+        """Configure Astrolabe for the specified MCP server.
+
+        Returns:
+            Dict with client_id and client_secret
+        """
+        logger.info(
+            f"Configuring Astrolabe for MCP server: {mcp_server_internal_url} (public: {mcp_server_public_url})"
+        )
+
+        # Configure MCP server URLs in Nextcloud system config
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "app",
+                "php",
+                "/var/www/html/occ",
+                "config:system:set",
+                "mcp_server_url",
+                "--value",
+                mcp_server_internal_url,
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"Failed to configure MCP server URL. "
+                f"Command failed with code {result.returncode}. "
+                f"stderr: {result.stderr}, stdout: {result.stdout}"
+            )
+
+        # Verify mcp_server_url was actually set
+        verify_result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "app",
+                "php",
+                "/var/www/html/occ",
+                "config:system:get",
+                "mcp_server_url",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        actual_url = verify_result.stdout.strip()
+        if actual_url != mcp_server_internal_url:
+            raise RuntimeError(
+                f"MCP server URL verification failed. "
+                f"Expected: {mcp_server_internal_url}, Got: {actual_url}"
+            )
+
+        logger.info(f"✓ MCP server URL configured and verified: {actual_url}")
+
+        # Configure public URL
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "app",
+                "php",
+                "/var/www/html/occ",
+                "config:system:set",
+                "mcp_server_public_url",
+                "--value",
+                mcp_server_public_url,
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"Failed to configure MCP server public URL. "
+                f"Command failed with code {result.returncode}. "
+                f"stderr: {result.stderr}, stdout: {result.stdout}"
+            )
+
+        logger.info(f"✓ MCP server public URL configured: {mcp_server_public_url}")
+
+        # Remove existing OAuth client if it exists
+        try:
+            subprocess.run(
+                [
+                    "docker",
+                    "compose",
+                    "exec",
+                    "-T",
+                    "app",
+                    "php",
+                    "/var/www/html/occ",
+                    "oidc:remove",
+                    client_id,
+                ],
+                check=False,  # Don't fail if client doesn't exist
+                capture_output=True,
+            )
+            logger.info(f"Removed existing OAuth client: {client_id}")
+        except Exception:
+            pass
+
+        # Create OAuth client for Astrolabe
+        redirect_uri = "http://localhost:8080/apps/astrolabe/oauth/callback"
+
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "app",
+                "php",
+                "/var/www/html/occ",
+                "oidc:create",
+                "Astrolabe",
+                redirect_uri,
+                "--client_id",
+                client_id,
+                "--type",
+                "confidential",
+                "--flow",
+                "code",
+                "--token_type",
+                "jwt",
+                "--resource_url",
+                mcp_server_public_url,
+                "--allowed_scopes",
+                "openid profile email offline_access notes:read notes:write calendar:read calendar:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write",
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+
+        # Parse client_secret from JSON output
+        client_output = json.loads(result.stdout.strip())
+        client_secret = client_output.get("client_secret")
+
+        if not client_secret:
+            raise ValueError(
+                "Failed to extract client_secret from OAuth client creation"
+            )
+
+        logger.info(f"✓ OAuth client created: {client_id}")
+
+        # Store client credentials in Nextcloud system config
+        subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "app",
+                "php",
+                "/var/www/html/occ",
+                "config:system:set",
+                "astrolabe_client_id",
+                "--value",
+                client_id,
+            ],
+            check=True,
+            capture_output=True,
+        )
+
+        subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "app",
+                "php",
+                "/var/www/html/occ",
+                "config:system:set",
+                "astrolabe_client_secret",
+                "--value",
+                client_secret,
+            ],
+            check=True,
+            capture_output=True,
+        )
+
+        logger.info("✓ Client credentials stored in system config")
+        logger.info(f"Astrolabe configured for MCP server: {mcp_server_public_url}")
+
+        return {"client_id": client_id, "client_secret": client_secret}
+
+    return _configure

tests/integration/client/test_document_processing_progress.py

@@ -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")

tests/integration/conftest.py

@@ -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"]

tests/integration/test_app_password_provisioning.py

@@ -0,0 +1,262 @@
+"""Integration tests for app password provisioning via management API.
+
+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 cryptography.fernet import Fernet
+
+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_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",
+        storage=temp_storage,
+    )
+
+    # Verify client was created with correct credentials
+    assert client is not None
+    assert client.username == "test_user"
+
+
+@pytest.mark.integration
+async def test_basic_auth_mode_raises_error_without_app_password(temp_storage):
+    """Test that BasicAuth mode raises NotProvisionedError if no app password.
+
+    There is NO fallback to OAuth - if no app password, user must provision one.
+    """
+    # Don't store any app password
+
+    # 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",
+            nextcloud_host="http://localhost:8080",
+            storage=temp_storage,
+        )
+
+    # 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_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.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 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 error message mentions OAuth provisioning
+    assert "oauth" in str(exc_info.value).lower()
+    assert "test_user" in str(exc_info.value)
+
+
+@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,
+        )

tests/integration/test_astrolabe_plotly_visualization.py

@@ -0,0 +1,371 @@
+"""Integration test for Astrolabe Plotly 3D visualization with multi-user BasicAuth mode.
+
+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()

tests/integration/test_astrolabe_settings_buttons.py

@@ -0,0 +1,91 @@
+"""Integration tests for Astrolabe personal settings page buttons.
+
+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)
+
+These tests verify that:
+- The endpoints respond correctly to POST requests
+- CSRF token validation works
+- User actions are properly handled
+- Appropriate redirects occur
+"""
+
+import httpx
+import pytest
+
+
+@pytest.mark.integration
+async def test_disable_indexing_button_endpoint_exists():
+    """Test that the Disable Indexing endpoint is accessible."""
+    async with httpx.AsyncClient() as client:
+        # Try without authentication - should return 401 or redirect
+        response = await client.post(
+            "http://localhost:8080/apps/astrolabe/api/revoke",
+            follow_redirects=False,
+        )
+
+        # Should get 401 Unauthorized or 30x redirect
+        assert response.status_code in [401, 301, 302, 303, 307, 308], (
+            f"Expected 401 or redirect without auth, got {response.status_code}"
+        )
+
+
+@pytest.mark.integration
+async def test_disconnect_button_endpoint_exists():
+    """Test that the Disconnect endpoint is accessible."""
+    async with httpx.AsyncClient() as client:
+        # Try without authentication - should return 401 or redirect
+        response = await client.post(
+            "http://localhost:8080/apps/astrolabe/oauth/disconnect",
+            follow_redirects=False,
+        )
+
+        # Should get 401 Unauthorized or 30x redirect
+        assert response.status_code in [401, 301, 302, 303, 307, 308], (
+            f"Expected 401 or redirect without auth, got {response.status_code}"
+        )
+
+
+@pytest.mark.integration
+async def test_settings_page_renders_buttons():
+    """Test that the settings page template includes button forms.
+
+    This test verifies that the PHP template renders the form elements.
+    It doesn't require authentication since we're just checking the route exists.
+    """
+    async with httpx.AsyncClient(follow_redirects=False) as client:
+        # Try to access settings page
+        response = await client.get("http://localhost:8080/settings/user/astrolabe")
+
+        # Should get 401/redirect if not authenticated (expected)
+        # or 200 if user session exists from browser testing
+        assert response.status_code in [200, 401, 302, 303, 307, 308], (
+            f"Unexpected status code: {response.status_code}"
+        )
+
+
+@pytest.mark.integration
+@pytest.mark.skip(
+    reason="Requires manual authentication - test with Playwright instead"
+)
+async def test_disconnect_button_functionality():
+    """Test that clicking Disconnect button clears user OAuth tokens.
+
+    NOTE: This test is skipped because programmatic login to Nextcloud is complex.
+    Use Playwright-based tests or manual testing instead.
+    """
+    pass
+
+
+@pytest.mark.integration
+@pytest.mark.skip(
+    reason="Requires manual authentication - test with Playwright instead"
+)
+async def test_disable_indexing_button_functionality():
+    """Test that clicking Disable Indexing button revokes background access.
+
+    NOTE: This test is skipped because programmatic login to Nextcloud is complex.
+    Use Playwright-based tests or manual testing instead.
+    """
+    pass

tests/integration/test_astrolabe_token_refresh.py

@@ -0,0 +1,695 @@
+"""Integration tests for Astrolabe token refresh flow.
+
+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)

tests/integration/test_deck_reorder_card.py

@@ -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}")

tests/integration/test_multi_user_basic_auth.py

@@ -0,0 +1,74 @@
+"""Integration tests for multi-user BasicAuth pass-through mode.
+
+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_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_search_notes", {"query": "test"}
+    )
+
+    # Verify tool executed successfully with pass-through auth
+    assert response is not None
+    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
+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_note",
+        {
+            "title": "BasicAuth Test Note",
+            "content": "This note was created via BasicAuth pass-through",
+            "category": "Test",
+        },
+    )
+
+    assert response is not None
+    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_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_get_note", {"note_id": note_id}
+    )
+
+    assert response is not None
+    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")

tests/integration/test_qdrant_collection_creation.py

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

tests/integration/test_rag.py

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