bump: version 0.56.0 → 0.56.1

bump: version 0.60.0 → 0.60.1
fix(mcp): Move all imports to the top of modules
2025-12-26 10:33:20 -06:00 · 2025-12-26 16:05:51 +00:00 · 2025-12-26 10:05:27 -06:00 · 2025-12-26 15:17:32 +00:00 · 2025-12-26 15:17:31 +00:00 · 2025-12-26 15:17:31 +00:00
129 changed files with 11430 additions and 6280 deletions
@@ -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 }}
@@ -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: |
@@ -130,29 +130,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
@@ -33,7 +33,7 @@ jobs:

      - name: Run Claude Code Review
        id: claude-review
-        uses: anthropics/claude-code-action@d7b6d50442a89f005016e778bf825a72ef582525 # v1
+        uses: anthropics/claude-code-action@7145c3e0510bcdbdd29f67cc4a8c1958f1acfa2f # v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
@@ -32,7 +32,7 @@ jobs:

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

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

 jobs:
  release:
@@ -48,6 +48,23 @@ 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
        with:
@@ -5,6 +5,77 @@ 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.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
@@ -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
@@ -4,8 +4,8 @@ set -euox pipefail

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

-# Set overwrite settings for URL generation (needed for OIDC discovery to return correct URLs)
-# These ensure that URLs generated by Nextcloud include the correct host:port
-php /var/www/html/occ config:system:set overwritehost --value="localhost:8080"
-php /var/www/html/occ config:system:set overwriteprotocol --value="http"
+# Set overwrite.cli.url to the external URL for OIDC discovery
+# This ensures OAuth flows redirect to the correct external URL
+# Important: The Astrolabe OAuth controller makes internal HTTP requests to /.well-known/openid-configuration
+# which needs to return URLs reachable by external browsers (localhost:8080, not localhost:80)
 php /var/www/html/occ config:system:set overwrite.cli.url --value="http://localhost:8080"
@@ -2,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."
@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.54.0"
+version = "0.56.1"
 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}}"
@@ -14,6 +14,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configurable resource limits
 - Grafana dashboard annotations

+## 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
@@ -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"
+digest: sha256:7f0979ec4110ff41ebeb55bf586b41366a350cc39fe65a2da7d2da03f723fe9b
+generated: "2025-12-22T11:09:39.166328543Z"
@@ -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.56.1
+appVersion: "0.60.1"
 keywords:
  - nextcloud
  - mcp
@@ -27,7 +27,7 @@ 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
@@ -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

@@ -208,16 +208,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 +427,7 @@ nextcloud:
  host: https://cloud.example.com
  # mcpServerUrl and publicIssuerUrl are optional!
  # If not set, mcpServerUrl defaults to ingress host or localhost
-  # publicIssuerUrl defaults to nextcloud.host
+  # publicIssuerUrl defaults to nextcloud.host (only used for browser-accessible auth endpoint)

 auth:
  mode: oauth
@@ -459,7 +459,7 @@ This example shows OAuth without pre-registered credentials (using DCR) and opti
 nextcloud:
  host: https://cloud.example.com
  # mcpServerUrl will automatically use ingress host (https://mcp.example.com)
-  # publicIssuerUrl will automatically default to nextcloud.host
+  # publicIssuerUrl will automatically default to nextcloud.host (only used for browser-accessible auth endpoint)

 auth:
  mode: oauth
@@ -537,8 +537,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 +576,7 @@ ollama:
 Or use an external Ollama instance:

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

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

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

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

 1. **Connection refused to Nextcloud**
   - Verify `nextcloud.host` is accessible from the Kubernetes cluster
+   - For OAuth mode: Ensure MCP server can reach OIDC discovery endpoints (token, JWKS, introspection, userinfo URLs)
   - Check network policies and firewall rules
+   - Note: Do not use internal Docker hostnames (like `http://app:80`) for `nextcloud.host` - use externally resolvable URLs

 2. **Authentication failures**
   - For basic auth: verify username/password are correct
@@ -69,12 +69,12 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
   {{- end }}
 {{- end }}

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

-5. Vector Search & Semantic Capabilities:
-   - Vector Sync: Enabled
-   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
-   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
+5. Semantic Search & Vector Capabilities:
+   - Semantic Search: Enabled
+   - Scan Interval: {{ .Values.semanticSearch.scanInterval }}s
+   - Processor Workers: {{ .Values.semanticSearch.processorWorkers }}
   {{- if .Values.qdrant.enabled }}
   - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
   {{- else }}
@@ -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
 */}}
@@ -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,6 +286,10 @@ spec:
            - name: oauth-storage
              mountPath: /app/.oauth
            {{- end }}
+            {{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled }}
+            - name: token-storage
+              mountPath: /app/data
+            {{- end }}
            {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
            - name: qdrant-data
              mountPath: /app/data
@@ -266,6 +305,11 @@ spec:
          persistentVolumeClaim:
            claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
        {{- end }}
+        {{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled }}
+        - name: token-storage
+          persistentVolumeClaim:
+            claimName: {{ include "nextcloud-mcp-server.multiUserBasicPvcName" . }}
+        {{- end }}
        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
        - name: qdrant-data
          persistentVolumeClaim:
@@ -16,6 +16,24 @@ spec:
      storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
 ---
+{{- if and (eq .Values.auth.mode "multi-user-basic") .Values.auth.multiUserBasic.enableOfflineAccess .Values.auth.multiUserBasic.persistence.enabled (not .Values.auth.multiUserBasic.persistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-token-storage
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.auth.multiUserBasic.persistence.accessMode }}
+  {{- if .Values.auth.multiUserBasic.persistence.storageClass }}
+  storageClassName: {{ .Values.auth.multiUserBasic.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.auth.multiUserBasic.persistence.size }}
+{{- end }}
+---
 {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.existingClaim) }}
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -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
@@ -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"
@@ -316,10 +365,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 +380,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
@@ -35,7 +35,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
@@ -87,7 +87,7 @@ services:
      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080

      # Vector sync configuration (ADR-007)
-      - VECTOR_SYNC_ENABLED=true
+      #- VECTOR_SYNC_ENABLED=true
      - VECTOR_SYNC_SCAN_INTERVAL=60
      - VECTOR_SYNC_PROCESSOR_WORKERS=1

@@ -123,6 +123,41 @@ 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_OFFLINE_ACCESS=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
+
+      # Token storage (required for middleware initialization)
+      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
+      - TOKEN_STORAGE_DB=/app/data/tokens.db
+
+      - VECTOR_SYNC_ENABLED=true
+      - 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 +178,8 @@ 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_OFFLINE_ACCESS=true
+      - ENABLE_BACKGROUND_OPERATIONS=true
      - TOKEN_ENCRYPTION_KEY=ESF1BvEQdGYsCluwMx9Cxvw3uh5pFowPH7Rg_nIliyo=
      - TOKEN_STORAGE_DB=/app/data/tokens.db

@@ -152,13 +188,19 @@ services:
      # No token exchange needed - tokens work for both MCP auth and Nextcloud APIs

      # Vector sync configuration (ADR-007)
-      - VECTOR_SYNC_ENABLED=true
+      - ENABLE_SEMANTIC_SEARCH=true
+      #- VECTOR_SYNC_ENABLED=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)
@@ -215,7 +257,8 @@ services:
      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8888/realms/nextcloud-mcp

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

@@ -280,3 +323,4 @@ volumes:
  keycloak-oauth-storage:
  qdrant-data:
  mcp-data:
+  multi-user-basic-data:
@@ -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`
@@ -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
+```
@@ -140,6 +140,93 @@ 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 |
+
+### 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:
@@ -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.
@@ -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
@@ -545,6 +657,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 +666,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
@@ -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"
@@ -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
@@ -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
@@ -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
@@ -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
@@ -11,11 +11,11 @@ The PHP app obtains tokens through PKCE flow and uses them to access these endpo
 """

 import logging
-import os
 import time
 from importlib.metadata import version
 from typing import Any

+import httpx
 from starlette.requests import Request
 from starlette.responses import JSONResponse

@@ -55,6 +55,22 @@ async def validate_token_and_get_user(
 ) -> tuple[str, dict[str, Any]]:
    """Validate OAuth bearer token and extract user ID.

+    Uses verify_token_for_management_api which accepts any valid Nextcloud OIDC
+    token (not just MCP-audience tokens). This is needed because Astrolabe
+    (NC PHP app) uses its own OAuth client, separate from MCP server's client.
+
+    Security Model:
+    ~~~~~~~~~~~~~~~
+    - **Authentication** (this function): Verifies token is cryptographically valid
+      and extracts user identity from the `sub` claim.
+    - **Authorization** (calling endpoints): Each endpoint MUST verify that the
+      authenticated user owns the requested resource. For example:
+      - GET /users/{user_id}/session: Checks token_user_id == path_user_id (403 if mismatch)
+      - POST /users/{user_id}/revoke: Checks token_user_id == path_user_id (403 if mismatch)
+
+    This separation ensures that even without audience validation, users can only
+    access their own resources. Cross-user access is blocked at the authorization layer.
+
    Args:
        request: Starlette request with Authorization header

@@ -72,9 +88,10 @@ async def validate_token_and_get_user(
    # Note: This is set in app.py starlette_lifespan for OAuth mode
    token_verifier = request.app.state.oauth_context["token_verifier"]

-    # Validate token (handles both JWT and opaque tokens)
-    # verify_token returns AccessToken object or None
-    access_token = await token_verifier.verify_token(token)
+    # Validate token for management API (handles both JWT and opaque tokens)
+    # Uses verify_token_for_management_api which accepts any valid Nextcloud token
+    # without requiring MCP audience - needed for Astrolabe integration (ADR-018)
+    access_token = await token_verifier.verify_token_for_management_api(token)

    if not access_token:
        raise ValueError("Token validation failed")
@@ -182,14 +199,23 @@ async def get_server_status(request: Request) -> JSONResponse:
    # Calculate uptime
    uptime_seconds = int(time.time() - _server_start_time)

-    # Determine auth mode
-    nextcloud_username = os.getenv("NEXTCLOUD_USERNAME")
-    nextcloud_password = os.getenv("NEXTCLOUD_PASSWORD")
+    # Determine auth mode using proper mode detection
+    from nextcloud_mcp_server.config_validators import AuthMode, detect_auth_mode

-    if nextcloud_username and nextcloud_password:
-        auth_mode = "basic"
-    else:
+    mode = detect_auth_mode(settings)
+
+    # Map deployment mode to auth_mode for API response
+    # This helps clients (like Astrolabe) determine which auth flow to use
+    if mode == AuthMode.OAUTH_SINGLE_AUDIENCE or mode == AuthMode.OAUTH_TOKEN_EXCHANGE:
        auth_mode = "oauth"
+    elif mode == AuthMode.MULTI_USER_BASIC:
+        auth_mode = "multi_user_basic"
+    elif mode == AuthMode.SINGLE_USER_BASIC:
+        auth_mode = "basic"
+    elif mode == AuthMode.SMITHERY_STATELESS:
+        auth_mode = "smithery"
+    else:
+        auth_mode = "unknown"

    response_data = {
        "version": __version__,
@@ -199,6 +225,10 @@ async def get_server_status(request: Request) -> JSONResponse:
        "management_api_version": "1.0",
    }

+    # Add app password support indicator for multi-user BasicAuth mode
+    if mode == AuthMode.MULTI_USER_BASIC:
+        response_data["supports_app_passwords"] = settings.enable_offline_access
+
    # Include OIDC configuration if in OAuth mode
    if auth_mode == "oauth":
        # Provide IdP discovery information for NC PHP app
@@ -334,11 +364,12 @@ async def get_user_session(request: Request) -> JSONResponse:
        )

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

    if not enable_offline_access:
        # Offline access disabled - return minimal session info
@@ -500,8 +531,6 @@ async def get_installed_apps(request: Request) -> JSONResponse:
        )

    try:
-        import httpx
-
        # Get Bearer token from request
        token = extract_bearer_token(request)
        if not token:
@@ -572,8 +601,6 @@ async def list_webhooks(request: Request) -> JSONResponse:
        )

    try:
-        import httpx
-
        from nextcloud_mcp_server.client.webhooks import WebhooksClient

        # Get Bearer token from request
@@ -639,8 +666,6 @@ async def create_webhook(request: Request) -> JSONResponse:
        )

    try:
-        import httpx
-
        from nextcloud_mcp_server.client.webhooks import WebhooksClient

        # Parse request body
@@ -717,8 +742,6 @@ async def delete_webhook(request: Request) -> JSONResponse:
        )

    try:
-        import httpx
-
        from nextcloud_mcp_server.client.webhooks import WebhooksClient

        # Get webhook_id from path parameter
@@ -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
+        }
@@ -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})"
@@ -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)
@@ -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}")
@@ -9,6 +9,7 @@ import functools
 import logging
 from typing import Callable

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

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

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

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

            # In offline access mode, check if Nextcloud scopes require provisioning
            if enable_offline_access:
@@ -28,6 +28,7 @@ Sensitive data (tokens, secrets) is encrypted at rest using Fernet symmetric enc
 import json
 import logging
 import os
+import socket
 import time
 from pathlib import Path
 from typing import Any, Optional
@@ -830,7 +831,6 @@ class RefreshTokenStorage:
            resource_id: Resource identifier
            auth_method: Authentication method used
        """
-        import socket

        hostname = socket.gethostname()
        timestamp = int(time.time())
@@ -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()

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

@@ -385,8 +386,6 @@ async def _get_user_info(request: Request) -> dict[str, Any]:
        return user_context

    except Exception as e:
-        import traceback
-
        logger.error(f"Error retrieving user info: {e}")
        logger.error(f"Traceback: {traceback.format_exc()}")
        return {
@@ -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={
@@ -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")
@@ -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)
@@ -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),
+    )
@@ -6,6 +6,8 @@ import tempfile
 from collections.abc import Awaitable, Callable
 from typing import Any, Optional

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

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

+import anyio
 from fastembed import SparseTextEmbedding

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

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

        # Run CPU-bound BM25 encoding in thread pool to avoid blocking event loop
        sparse_embeddings = await anyio.to_thread.run_sync(  # type: ignore[attr-defined]
@@ -6,6 +6,7 @@ provides CLI integration.
 """

 import logging
+import sqlite3
 from pathlib import Path

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

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

+import functools
 import logging
+import time

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

    from nextcloud_mcp_server.observability.tracing import trace_operation

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

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

+from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+

@runtime_checkable
 class NextcloudClientProtocol(Protocol):
@@ -78,13 +85,6 @@ async def get_indexed_doc_types(user_id: str) -> set[str]:
        >>> if "note" in types:
        ...     # Search notes
    """
-    import logging
-
-    from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-    from nextcloud_mcp_server.config import get_settings
-    from nextcloud_mcp_server.vector.placeholder import get_placeholder_filter
-    from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

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

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

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

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

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

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

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

        # Clean up temp directory and extracted images
-        import shutil

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

        temp_pdf_path = None
        try:
@@ -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
@@ -1,6 +1,7 @@
 """Semantic search MCP tools using vector database."""

 import logging
+import os

 import anyio
 from httpx import RequestError
@@ -656,7 +657,6 @@ 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 = (
@@ -1,3 +1,4 @@
+import base64
 import logging

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

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

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

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

+import anyio
 from langchain_text_splitters import RecursiveCharacterTextSplitter

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

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

 import logging
+import re

 from markdownify import markdownify as md

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

        text = re.sub(r"<[^>]+>", " ", html_content)
        return " ".join(text.split())  # Normalize whitespace
@@ -1,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 obtained via Astrolabe Management API
+- Users provision via Astrolabe personal settings
+- 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,7 +31,9 @@ from anyio.streams.memory import (
    MemoryObjectReceiveStream,
    MemoryObjectSendStream,
 )
+from httpx import BasicAuth

+from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import get_settings
 from nextcloud_mcp_server.vector.scanner import DocumentTask, scan_user_documents
@@ -53,12 +68,64 @@ 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,
+) -> NextcloudClient:
+    """Get an authenticated NextcloudClient using app password (BasicAuth mode).
+
+    For multi-user BasicAuth deployments where users provision app passwords
+    via Astrolabe personal settings. OAuth is NOT used in this mode.
+
+    Args:
+        user_id: User identifier
+        nextcloud_host: Nextcloud base URL
+
+    Returns:
+        Authenticated NextcloudClient with BasicAuth
+
+    Raises:
+        NotProvisionedError: If user has not provisioned an app password
+    """
+    settings = get_settings()
+
+    if not settings.oidc_client_id or not settings.oidc_client_secret:
+        raise NotProvisionedError(
+            "Astrolabe client credentials not configured. "
+            "Set OIDC_CLIENT_ID and OIDC_CLIENT_SECRET for app password retrieval."
+        )
+
+    astrolabe = AstrolabeClient(
+        nextcloud_host=nextcloud_host,
+        client_id=settings.oidc_client_id,
+        client_secret=settings.oidc_client_secret,
+    )
+
+    app_password = await astrolabe.get_user_app_password(user_id)
+
+    if 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 +133,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 +153,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 +220,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 +234,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 +254,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 +294,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 +309,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 +323,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 +349,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 +368,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,35 +381,40 @@ 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():
@@ -297,7 +427,7 @@ async def user_manager_task(
            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 +446,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 +477,9 @@ async def user_manager_task(

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

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

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

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

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

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

    scan_id = random.randint(1000, 9999)
    logger.info(
@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.56.2"
+version = "0.60.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"
@@ -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
@@ -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
@@ -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
@@ -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:
@@ -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:
@@ -2384,9 +2415,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 +2555,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 +2705,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 +2740,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 +2874,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 +3207,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
@@ -1,6 +1,7 @@
 """Integration tests for document processing with progress notifications."""

 import io
+import os

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

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

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

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

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

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

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

@@ -24,3 +30,89 @@ def pytest_configure(config):
    config.addinivalue_line(
        "markers", "rag: mark test as RAG integration test (requires --provider flag)"
    )
+
+
+@pytest.fixture(autouse=True, scope="module")
+async def reset_all_singletons():
+    """Reset ALL global singletons between test modules.
+
+    Prevents anyio.WouldBlock errors caused by stale singleton state
+    from previous test modules holding references to dead event loops
+    or closed memory streams.
+    """
+    # Import all modules with singletons
+    import nextcloud_mcp_server.app as app_module
+    import nextcloud_mcp_server.auth.client_registry as client_registry_module
+    import nextcloud_mcp_server.auth.token_exchange as token_exchange_module
+    import nextcloud_mcp_server.embedding.service as embedding_module
+    import nextcloud_mcp_server.observability.tracing as tracing_module
+    import nextcloud_mcp_server.providers.registry as registry_module
+    import nextcloud_mcp_server.vector.qdrant_client as qdrant_module
+
+    # Store originals for restoration after test
+    originals = {
+        "qdrant_client": qdrant_module._qdrant_client,
+        "embedding_service": embedding_module._embedding_service,
+        "bm25_service": embedding_module._bm25_service,
+        "provider": registry_module._provider,
+        "vector_sync_state": (
+            app_module._vector_sync_state.document_send_stream,
+            app_module._vector_sync_state.document_receive_stream,
+            app_module._vector_sync_state.shutdown_event,
+            app_module._vector_sync_state.scanner_wake_event,
+        ),
+        "tracer": tracing_module._tracer,
+        "registry": client_registry_module._registry,
+        "token_exchange_service": token_exchange_module._token_exchange_service,
+    }
+
+    # Close any open memory streams before reset
+    if app_module._vector_sync_state.document_send_stream is not None:
+        try:
+            await app_module._vector_sync_state.document_send_stream.aclose()
+        except Exception:
+            pass
+    if app_module._vector_sync_state.document_receive_stream is not None:
+        try:
+            await app_module._vector_sync_state.document_receive_stream.aclose()
+        except Exception:
+            pass
+
+    # Reset all singletons to None/fresh state
+    qdrant_module._qdrant_client = None
+    embedding_module._embedding_service = None
+    embedding_module._bm25_service = None
+    registry_module._provider = None
+    app_module._vector_sync_state.document_send_stream = None
+    app_module._vector_sync_state.document_receive_stream = None
+    app_module._vector_sync_state.shutdown_event = None
+    app_module._vector_sync_state.scanner_wake_event = None
+    tracing_module._tracer = None
+    client_registry_module._registry = None
+    token_exchange_module._token_exchange_service = None
+
+    logger.debug("All singletons reset for test module")
+
+    yield
+
+    # Cleanup: Close async resources created during test
+    if qdrant_module._qdrant_client is not None:
+        try:
+            await qdrant_module._qdrant_client.close()
+        except Exception:
+            pass
+
+    # Restore originals
+    qdrant_module._qdrant_client = originals["qdrant_client"]
+    embedding_module._embedding_service = originals["embedding_service"]
+    embedding_module._bm25_service = originals["bm25_service"]
+    registry_module._provider = originals["provider"]
+    (
+        app_module._vector_sync_state.document_send_stream,
+        app_module._vector_sync_state.document_receive_stream,
+        app_module._vector_sync_state.shutdown_event,
+        app_module._vector_sync_state.scanner_wake_event,
+    ) = originals["vector_sync_state"]
+    tracing_module._tracer = originals["tracer"]
+    client_registry_module._registry = originals["registry"]
+    token_exchange_module._token_exchange_service = originals["token_exchange_service"]
@@ -0,0 +1,278 @@
+"""Integration tests for app password provisioning via Astrolabe.
+
+Tests the complete flow for multi-user BasicAuth mode:
+1. User stores app password via Astrolabe API
+2. MCP server retrieves it via OAuth client credentials
+3. Background sync uses it to access Nextcloud (NOT OAuth refresh tokens)
+
+These tests verify that BasicAuth and OAuth are completely separate concerns
+with no fallback between them.
+"""
+
+import pytest
+
+from nextcloud_mcp_server.auth.astrolabe_client import AstrolabeClient
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.vector.oauth_sync import (
+    NotProvisionedError,
+    get_user_client,
+    get_user_client_basic_auth,
+    get_user_client_oauth,
+)
+
+
+@pytest.mark.integration
+async def test_astrolabe_client_initialization():
+    """Test AstrolabeClient can be instantiated."""
+    client = AstrolabeClient(
+        nextcloud_host="http://localhost:8080",
+        client_id="test-client",
+        client_secret="test-secret",
+    )
+
+    assert client is not None
+    assert client.nextcloud_host == "http://localhost:8080"
+    assert client.client_id == "test-client"
+    assert client.client_secret == "test-secret"
+    assert client._token_cache is None
+
+
+@pytest.mark.integration
+async def test_astrolabe_client_get_access_token_requires_oidc():
+    """Test that getting access token requires OIDC discovery endpoint."""
+    client = AstrolabeClient(
+        nextcloud_host="http://localhost:8080",
+        client_id="test-client",
+        client_secret="test-secret",
+    )
+
+    # This will fail without proper OIDC setup, which is expected
+    # The test verifies the client follows the OAuth client credentials flow
+    try:
+        token = await client.get_access_token()
+        # If we get here, OIDC is configured
+        assert token is not None
+    except Exception as e:
+        # Expected if OIDC not fully configured for test client
+        # 400/401/403/404 all indicate the flow is working but credentials are invalid
+        assert any(code in str(e) for code in ["400", "401", "403", "404"])
+
+
+@pytest.mark.integration
+async def test_get_user_app_password_returns_none_for_unconfigured_user():
+    """Test that get_user_app_password returns None for users without app passwords."""
+    # This requires valid OAuth client credentials
+    settings = get_settings()
+
+    if not settings.oidc_client_id or not settings.oidc_client_secret:
+        pytest.skip("OAuth client credentials not configured")
+
+    client = AstrolabeClient(
+        nextcloud_host=settings.nextcloud_host or "http://localhost:8080",
+        client_id=settings.oidc_client_id,
+        client_secret=settings.oidc_client_secret,
+    )
+
+    # Try to get app password for a user that hasn't provisioned one
+    try:
+        app_password = await client.get_user_app_password("nonexistent_user")
+        # Should return None for unconfigured user (404 response)
+        assert app_password is None
+    except Exception as e:
+        # May fail with auth error if OAuth not fully configured
+        assert any(code in str(e) for code in ["400", "401", "403", "404"])
+
+
+@pytest.mark.integration
+async def test_basic_auth_mode_uses_app_password_only(mocker):
+    """Test that BasicAuth mode uses ONLY app passwords, NOT OAuth tokens.
+
+    In multi-user BasicAuth mode, OAuth refresh tokens are NOT used.
+    This is a complete separation of concerns.
+    """
+    # Mock settings to have client credentials
+    mock_settings = mocker.MagicMock()
+    mock_settings.oidc_client_id = "test-client-id"
+    mock_settings.oidc_client_secret = "test-client-secret"
+    mocker.patch(
+        "nextcloud_mcp_server.vector.oauth_sync.get_settings",
+        return_value=mock_settings,
+    )
+
+    # Mock AstrolabeClient to return an app password
+    mock_astrolabe = mocker.AsyncMock()
+    mock_astrolabe.get_user_app_password.return_value = "test-app-password-12345"
+
+    mocker.patch(
+        "nextcloud_mcp_server.vector.oauth_sync.AstrolabeClient",
+        return_value=mock_astrolabe,
+    )
+
+    # Call get_user_client in BasicAuth mode
+    _client = await get_user_client(
+        user_id="test_user",
+        token_broker=None,  # No token broker needed for BasicAuth mode
+        nextcloud_host="http://localhost:8080",
+        use_basic_auth=True,
+    )
+
+    # Verify app password was requested
+    mock_astrolabe.get_user_app_password.assert_called_once_with("test_user")
+
+    # Verify client was created successfully with correct username
+    assert _client is not None
+    assert _client.username == "test_user"
+
+
+@pytest.mark.integration
+async def test_basic_auth_mode_raises_error_without_app_password(mocker):
+    """Test that BasicAuth mode raises NotProvisionedError if no app password.
+
+    There is NO fallback to OAuth - if no app password, user must provision one.
+    """
+    # Mock settings to have client credentials
+    mock_settings = mocker.MagicMock()
+    mock_settings.oidc_client_id = "test-client-id"
+    mock_settings.oidc_client_secret = "test-client-secret"
+    mocker.patch(
+        "nextcloud_mcp_server.vector.oauth_sync.get_settings",
+        return_value=mock_settings,
+    )
+
+    # Mock AstrolabeClient to return None (no app password)
+    mock_astrolabe = mocker.AsyncMock()
+    mock_astrolabe.get_user_app_password.return_value = None
+
+    mocker.patch(
+        "nextcloud_mcp_server.vector.oauth_sync.AstrolabeClient",
+        return_value=mock_astrolabe,
+    )
+
+    # Call get_user_client in BasicAuth mode - should raise NotProvisionedError
+    with pytest.raises(NotProvisionedError) as exc_info:
+        await get_user_client(
+            user_id="test_user",
+            token_broker=None,
+            nextcloud_host="http://localhost:8080",
+            use_basic_auth=True,
+        )
+
+    # 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_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 (NOT Astrolabe)
+    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_basic_auth_function(mocker):
+    """Test the dedicated get_user_client_basic_auth function."""
+    # Mock settings to have client credentials
+    mock_settings = mocker.MagicMock()
+    mock_settings.oidc_client_id = "test-client-id"
+    mock_settings.oidc_client_secret = "test-client-secret"
+    mocker.patch(
+        "nextcloud_mcp_server.vector.oauth_sync.get_settings",
+        return_value=mock_settings,
+    )
+
+    # Mock AstrolabeClient
+    mock_astrolabe = mocker.AsyncMock()
+    mock_astrolabe.get_user_app_password.return_value = "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+
+    mocker.patch(
+        "nextcloud_mcp_server.vector.oauth_sync.AstrolabeClient",
+        return_value=mock_astrolabe,
+    )
+
+    # Call dedicated function
+    client = await get_user_client_basic_auth(
+        user_id="alice",
+        nextcloud_host="http://localhost:8080",
+    )
+
+    assert client is not None
+    assert client.username == "alice"
+    mock_astrolabe.get_user_app_password.assert_called_once_with("alice")
+
+
+@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
+        )
@@ -0,0 +1,561 @@
+"""Integration test for multi-user Astrolabe background sync enablement.
+
+This test verifies that multiple users can independently:
+1. Log in to Nextcloud
+2. Generate an app password in Security settings
+3. Enter the app password in Astrolabe personal settings
+4. Enable background sync for the mcp-multi-user-basic service
+5. Verify app password is stored in the database
+
+Tests the complete app password provisioning flow:
+user login → Security settings → app password generation → Astrolabe settings →
+app password entry → background sync activation → database verification.
+"""
+
+import logging
+import re
+import subprocess
+
+import anyio
+import pytest
+from playwright.async_api import Page
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+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 navigate_to_astrolabe_settings(page: Page):
+    """Navigate to Astrolabe personal settings page.
+
+    Args:
+        page: Playwright page instance (must be authenticated)
+    """
+    nextcloud_url = "http://localhost:8080"
+    settings_url = f"{nextcloud_url}/settings/user/astrolabe"
+
+    logger.info(f"Navigating to Astrolabe settings: {settings_url}")
+    await page.goto(settings_url, wait_until="networkidle", timeout=30000)
+
+    # Verify we're on the settings page
+    current_url = page.url
+    assert "/settings/user/astrolabe" in current_url, (
+        f"Failed to navigate to Astrolabe settings, current URL: {current_url}"
+    )
+    logger.info("✓ Successfully loaded Astrolabe settings page")
+
+
+async def generate_app_password(
+    page: Page, username: str, app_name: str = "Astrolabe Background Sync"
+) -> 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 (selector confirmed via Playwright MCP)
+    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 (needs 1 second, not 0.5)
+    await anyio.sleep(1.0)
+    logger.info("Waited for Vue.js to process input and enable button")
+
+    # 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 and displayed in the dialog
+    await anyio.sleep(3)  # Give it more time to generate and display
+
+    # Find the Login input field which should have the username value
+    # Then find the Password input field which is in the same form
+    app_password = None
+    try:
+        # Wait for heading "New app password" to appear
+        await page.wait_for_selector('text="New app password"', timeout=10000)
+        logger.info("App password dialog appeared with heading")
+
+        # Get all visible input elements
+        all_inputs = await page.locator('input[type="text"]').all()
+        logger.info(f"Found {len(all_inputs)} text input elements")
+
+        # Check each input to find the one with the app password
+        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}: '{app_password}' (length: {len(app_password)})"
+                    )
+                    break
+            except Exception as e:
+                logger.debug(f"Could not get value from input {idx}: {e}")
+                continue
+
+    except Exception as e:
+        logger.error(f"Failed to find app password dialog or extract password: {e}")
+
+    if not app_password:
+        # Take screenshot for debugging
+        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 before returning
+
+    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,
+    ):
+        logger.error(
+            f"Extracted password does not match expected format: '{app_password}'"
+        )
+        logger.error(f"Password repr: {repr(app_password)}")
+        screenshot_path = f"/tmp/app_password_invalid_format_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        raise ValueError(
+            f"App password format validation failed. Screenshot: {screenshot_path}"
+        )
+
+    logger.info(
+        f"✓ Generated app password for {username}: {app_password[:10]}... (validated)"
+    )
+
+    # Close the dialog by clicking the Close button
+    close_button = page.get_by_role("button", name="Close")
+    await close_button.click()
+    logger.info("Closed app password dialog")
+    await anyio.sleep(0.5)
+
+    return app_password
+
+
+async def enable_background_sync_via_app_password(
+    page: Page, username: str, app_password: str
+):
+    """Enable background sync by entering app password in Astrolabe settings.
+
+    Args:
+        page: Playwright page instance
+        username: Username (for logging)
+        app_password: App password to enter
+
+    Returns:
+        True if background sync was enabled successfully
+    """
+    logger.info(f"Enabling background sync via app password for {username}...")
+
+    nextcloud_url = "http://localhost:8080"
+
+    # Set up network request and console listeners BEFORE navigation
+    network_requests = []
+    network_responses = []
+    console_messages = []
+
+    def log_request(req):
+        network_requests.append(f"{req.method} {req.url}")
+
+    def log_response(resp):
+        response_info = f"{resp.status} {resp.url}"
+        network_responses.append(response_info)
+        logger.info(f"Response: {response_info}")
+
+    def log_console(msg):
+        console_messages.append(f"[{msg.type}] {msg.text}")
+
+    page.on("request", log_request)
+    page.on("response", log_response)
+    page.on("console", log_console)
+
+    # Navigate to Astrolabe settings
+    await page.goto(
+        f"{nextcloud_url}/settings/user/astrolabe", wait_until="networkidle"
+    )
+
+    # Wait for page to load
+    await anyio.sleep(1)
+
+    # Check if already active (look for "Active" text in the Background Sync Access section)
+    try:
+        # The "Active" badge appears as a <span> with text "Active"
+        active_text = page.get_by_text("Active", exact=True)
+        if await active_text.is_visible(timeout=2000):
+            logger.info(f"✓ Background sync already active for {username}")
+            return True
+    except Exception:
+        pass
+
+    # Find the app password input field using the placeholder text
+    # Based on manual testing: textbox with placeholder "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+    app_password_input = page.get_by_placeholder("xxxxx-xxxxx-xxxxx-xxxxx-xxxxx")
+
+    try:
+        await app_password_input.wait_for(timeout=5000, state="visible")
+        logger.info("Found app password input field")
+    except Exception:
+        # Take screenshot for debugging
+        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 for {username}. Screenshot: {screenshot_path}"
+        )
+
+    # Enter the app password
+    await app_password_input.fill(app_password)
+    logger.info(f"Entered app password for {username}")
+
+    # Wait a moment for any validation to complete
+    await anyio.sleep(0.5)
+
+    # Take screenshot before clicking Save to check for warnings
+    screenshot_path = f"/tmp/before_save_{username}.png"
+    await page.screenshot(path=screenshot_path)
+    logger.info(f"Screenshot taken before Save: {screenshot_path}")
+
+    # Find and click the Save button
+    save_button = page.get_by_role("button", name="Save")
+
+    # Check if Save button is enabled
+    is_disabled = await save_button.is_disabled()
+    logger.info(f"Save button disabled state: {is_disabled}")
+
+    await save_button.click()
+    logger.info("Clicked Save button")
+
+    # Give the request time to complete before checking logs
+    await anyio.sleep(0.5)
+
+    # Log network requests after clicking Save
+    logger.info(f"Network requests after Save for {username}:")
+    for req in network_requests[-10:]:  # Last 10 requests
+        logger.info(f"  {req}")
+
+    # Log network responses after clicking Save
+    logger.info(f"Network responses after Save for {username}:")
+    for resp in network_responses[-10:]:  # Last 10 responses
+        logger.info(f"  {resp}")
+
+    # Check specifically for the credentials POST response
+    credentials_responses = [
+        r for r in network_responses if "background-sync/credentials" in r
+    ]
+    if credentials_responses:
+        logger.info(f"Credentials endpoint response: {credentials_responses[-1]}")
+        if "200" not in credentials_responses[-1]:
+            logger.error(
+                f"Credentials POST did not return 200 OK: {credentials_responses[-1]}"
+            )
+    else:
+        logger.warning("No response found for credentials endpoint!")
+
+    # Wait for the page to reload after successful save
+    # The JavaScript in personalSettings.js does: setTimeout(() => window.location.reload(), 1000)
+    await page.wait_for_load_state("networkidle", timeout=15000)
+    await anyio.sleep(2)
+
+    # Log any console messages
+    if console_messages:
+        logger.info(f"Console messages for {username}:")
+        for msg in console_messages:
+            logger.info(f"  {msg}")
+
+    # Check for error notifications (toast messages)
+    try:
+        error_toast = page.locator(".toastify.toast-error, .toast-error")
+        if await error_toast.count() > 0:
+            error_text = await error_toast.first.text_content()
+            logger.error(f"Error notification for {username}: {error_text}")
+    except Exception:
+        pass
+
+    # Verify "Active" text appears after reload
+    try:
+        active_text = page.get_by_text("Active", exact=True)
+        await active_text.wait_for(timeout=5000, state="visible")
+        logger.info(f"✓ Background sync enabled for {username} - Active badge visible")
+        return True
+    except Exception:
+        # Take screenshot for debugging
+        screenshot_path = f"/tmp/astrolabe_after_password_{username}.png"
+        await page.screenshot(path=screenshot_path)
+        logger.error(
+            f"Active badge did not appear for {username}. Screenshot: {screenshot_path}"
+        )
+        raise
+
+
+async def verify_app_password_created(username: str) -> bool:
+    """Verify that background sync app password was stored for the user.
+
+    This checks the Nextcloud database for background sync credentials stored
+    by Astrolabe in the oc_preferences table.
+
+    Args:
+        username: Nextcloud username
+
+    Returns:
+        True if background sync app password exists
+    """
+    logger.info(f"Verifying background sync app password for {username}...")
+
+    # Query the database to check for background sync credentials
+    # Astrolabe stores app passwords in oc_preferences, not oc_authtoken
+
+    query = f"""
+    SELECT userid, configkey, configvalue
+    FROM oc_preferences
+    WHERE userid = '{username}'
+    AND appid = 'astrolabe'
+    AND configkey IN ('background_sync_password', 'background_sync_type', 'background_sync_provisioned_at')
+    ORDER BY configkey;
+    """
+
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "compose",
+                "exec",
+                "-T",
+                "db",
+                "mariadb",
+                "-u",
+                "root",
+                "-ppassword",
+                "nextcloud",
+                "-e",
+                query,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        output = result.stdout
+        logger.debug(f"Background sync credentials query result:\n{output}")
+
+        # Check if background sync credentials exist
+        # We should see 3 rows: background_sync_password, background_sync_type, background_sync_provisioned_at
+        lines = output.strip().split("\n")
+
+        if len(lines) >= 3:  # Header + at least 2 data rows (password + type)
+            # Verify background_sync_type is "app_password"
+            if "app_password" in output:
+                logger.info(f"✓ Background sync app password stored for {username}")
+                return True
+            else:
+                logger.warning(
+                    f"Background sync credentials found but type is not app_password for {username}"
+                )
+                return False
+        else:
+            logger.warning(f"No background sync credentials found for {username}")
+            return False
+
+    except Exception as e:
+        logger.error(f"Error checking background sync credentials for {username}: {e}")
+        return False
+
+
+@pytest.mark.integration
+@pytest.mark.oauth
+async def test_multi_user_astrolabe_background_sync_enablement(
+    browser,
+    nc_client,
+    test_users_setup,
+    configure_astrolabe_for_mcp_server,
+):
+    """Test that multiple users can independently enable background sync via app passwords.
+
+    This test verifies the complete app password provisioning flow:
+    1. Users log in to Nextcloud
+    2. Users generate app passwords in Security settings
+    3. Users navigate to Astrolabe personal settings
+    4. Users enter their app passwords in the Astrolabe form
+    5. Background sync becomes active with "Active" badge
+    6. App passwords are stored in the database (oc_authtoken table)
+    7. The process works correctly for multiple users
+
+    Requirements:
+    - Astrolabe app installed in Nextcloud and configured for mcp-multi-user-basic
+    - MCP server running in multi-user BasicAuth mode (mcp-multi-user-basic service)
+    - Test users (alice, bob) created with valid credentials
+
+    This tests ADR-002 Tier 2 authentication: User-specific app passwords for background operations
+    in multi-user BasicAuth deployments.
+    """
+    # Configure Astrolabe to point to the mcp-multi-user-basic server
+    logger.info("Configuring Astrolabe for mcp-multi-user-basic server...")
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-multi-user-basic:8000",
+        mcp_server_public_url="http://localhost:8003",
+    )
+
+    # Test users to check
+    test_users = ["alice", "bob"]
+
+    # Verify test users were created by the fixture
+    logger.info("Verifying test users exist in Nextcloud...")
+    for username in test_users:
+        try:
+            # Use nc_client to check if user exists
+            user_details = await nc_client.users.get_user_details(username)
+            logger.info(
+                f"✓ Confirmed {username} exists (display name: {user_details.displayname})"
+            )
+        except Exception as e:
+            raise AssertionError(
+                f"Test user {username} does not exist! "
+                f"test_users_setup fixture may have failed. Error: {e}"
+            )
+
+    results = {}
+
+    for username in test_users:
+        logger.info(f"\n{'=' * 60}")
+        logger.info(f"Testing background sync enablement for: {username}")
+        logger.info(f"{'=' * 60}")
+
+        user_config = test_users_setup[username]
+        password = user_config["password"]
+
+        # Create new browser context for this user
+        context = await browser.new_context(ignore_https_errors=True)
+        page = await context.new_page()
+
+        try:
+            # Step 1: Login to Nextcloud
+            await login_to_nextcloud(page, username, password)
+
+            # Step 2: Generate app password in Security settings
+            app_password = await generate_app_password(page, username)
+
+            # Step 3: Enable background sync by entering app password in Astrolabe
+            sync_enabled = await enable_background_sync_via_app_password(
+                page, username, app_password
+            )
+
+            # Step 4: Verify app password was stored in database
+            app_password_stored = await verify_app_password_created(username)
+
+            # Give it time to complete
+            await anyio.sleep(1)
+
+            results[username] = {
+                "settings_accessed": True,
+                "app_password_generated": bool(app_password),
+                "sync_enabled": sync_enabled,
+                "app_password_stored": app_password_stored,
+                "background_sync_active": sync_enabled and app_password_stored,
+            }
+
+            logger.info(f"\n{username} results:")
+            logger.info("  Settings accessed: ✓")
+            logger.info(f"  App password generated: {'✓' if app_password else '✗'}")
+            logger.info(f"  Sync enabled: {'✓' if sync_enabled else '✗'}")
+            logger.info(f"  App password stored: {'✓' if app_password_stored else '✗'}")
+            logger.info(
+                f"  Background sync active: {'✓' if (sync_enabled and app_password_stored) else '✗'}"
+            )
+
+        except Exception as e:
+            logger.error(f"Error during {username} test: {e}")
+            results[username] = {
+                "settings_accessed": False,
+                "app_password_generated": False,
+                "sync_enabled": False,
+                "app_password_stored": False,
+                "background_sync_active": False,
+                "error": str(e),
+            }
+
+        finally:
+            await context.close()
+
+    # Verify all users succeeded
+    logger.info(f"\n{'=' * 60}")
+    logger.info("Test Summary")
+    logger.info(f"{'=' * 60}")
+
+    for username, result in results.items():
+        logger.info(f"\n{username}:")
+        for key, value in result.items():
+            if key != "error":
+                status = "✓" if value else "✗"
+                logger.info(f"  {key}: {status}")
+            elif value:
+                logger.info(f"  error: {value}")
+
+    # Assert all users successfully enabled background sync
+    for username in test_users:
+        result = results[username]
+        assert result["settings_accessed"], (
+            f"{username} could not access Astrolabe settings"
+        )
+        assert result["app_password_generated"], (
+            f"{username} app password was not generated"
+        )
+        assert result["sync_enabled"], (
+            f"{username} background sync enablement did not complete successfully"
+        )
+        assert result["app_password_stored"], (
+            f"{username} app password was not stored in database"
+        )
+        assert result["background_sync_active"], (
+            f"{username} background sync is not active"
+        )
+
+    logger.info(
+        f"\n✓ All {len(test_users)} users successfully enabled background sync via app passwords!"
+    )
@@ -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
@@ -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")
@@ -10,12 +10,21 @@ These tests validate that:
 from unittest.mock import Mock

 import pytest
+from qdrant_client.models import VectorParams

 from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client

 pytestmark = pytest.mark.integration


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

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


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

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


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

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

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

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

    from qdrant_client.models import Distance

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


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

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

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

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

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

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

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

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

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

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

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

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

+import json
 from unittest.mock import MagicMock

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

 pytestmark = pytest.mark.integration


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

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

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

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

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

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

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

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

    # Wait for vector indexing to complete
-    import asyncio

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

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

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

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

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

    # Wait for vector indexing to complete
-    import asyncio

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

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

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

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

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

    # Wait for vector indexing to complete
-    import asyncio

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

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

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

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

    # Should not error, even if sampling fails
    assert result is not None
@@ -10,6 +10,7 @@ Uses SimpleEmbeddingProvider for deterministic, in-process embeddings
 without requiring external services like Ollama.
 """

+import math
 import tempfile
 from pathlib import Path

@@ -147,7 +148,6 @@ async def test_simple_embedding_provider_deterministic(simple_embedding_provider
    assert len(embedding1) == 384

    # Should be normalized (unit length)
-    import math

    norm = math.sqrt(sum(x * x for x in embedding1))
    assert abs(norm - 1.0) < 1e-6
@@ -340,7 +340,6 @@ async def test_batch_embedding(simple_embedding_provider: SimpleEmbeddingProvide
    assert all(len(emb) == 384 for emb in embeddings)

    # Each should be normalized
-    import math

    for emb in embeddings:
        norm = math.sqrt(sum(x * x for x in emb))
@@ -6,6 +6,7 @@ workflow completion rates, and cross-user operation latencies.
 """

 import statistics
+import time
 from collections import Counter, defaultdict
 from typing import Any

@@ -44,13 +45,11 @@ class OAuthBenchmarkMetrics:

    def start(self):
        """Mark the start of the benchmark."""
-        import time

        self.start_time = time.time()

    def stop(self):
        """Mark the end of the benchmark."""
-        import time

        self.end_time = time.time()

@@ -5,8 +5,12 @@ Manages multiple OAuth-authenticated users for realistic multi-user load testing
 """

 import logging
+import secrets
+import string
+import time
 from dataclasses import dataclass
 from typing import Any
+from urllib.parse import quote

 import anyio
 import httpx
@@ -333,8 +337,6 @@ class OAuthUserPool:
            TimeoutError: If callback not received within timeout
            ValueError: If token exchange fails
        """
-        import time
-        from urllib.parse import quote

        logger.info(f"Starting Playwright OAuth flow for {username}...")
        logger.debug(f"Using state: {state[:16]}...")
@@ -478,8 +480,6 @@ class UserSessionWrapper:

 def generate_secure_password(length: int = 20) -> str:
    """Generate a secure random password."""
-    import secrets
-    import string

    alphabet = string.ascii_letters + string.digits + "!@#$%^&*()"
    return "".join(secrets.choice(alphabet) for _ in range(length))
@@ -4,6 +4,7 @@ Workload definitions for load testing the MCP server.
 Defines realistic operation mixes and individual operation functions.
 """

+import json
 import logging
 import random
 import time
@@ -91,8 +92,6 @@ class WorkloadOperations:
            if result and len(result.content) > 0:
                content = result.content[0]
                if hasattr(content, "text"):
-                    import json
-
                    note_data = json.loads(content.text)
                    note_id = note_data.get("id")
                    if note_id:
@@ -222,8 +221,6 @@ class MixedWorkload:
                        "nc_notes_get_note", {"note_id": note_id}
                    )
                    if get_result and len(get_result.content) > 0:
-                        import json
-
                        note_data = json.loads(get_result.content[0].text)
                        etag = note_data.get("etag", "")
                        self._warmup_note_ids.append((note_id, etag))
@@ -18,6 +18,7 @@ Usage:
 import asyncio
 import logging
 import os
+import re
 import sys

 # Add parent directory to path
@@ -127,7 +128,6 @@ async def main():
        )

        # Extract requesttoken from HTML
-        import re

        token_match = re.search(r'data-requesttoken="([^"]+)"', settings_response.text)
        if token_match:
@@ -0,0 +1,104 @@
+"""Test Astrolabe integration with multiple MCP server deployments.
+
+This test suite verifies that the Astrolabe app can be dynamically configured
+to connect to different MCP server deployments (mcp-oauth, mcp-keycloak, etc.).
+
+The configuration is managed dynamically during tests using the
+configure_astrolabe_for_mcp_server fixture, which allows testing multiple
+deployment scenarios without requiring static post-installation configuration.
+"""
+
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+class TestAstrolabeMultiServerIntegration:
+    """Test suite for Astrolabe integration with multiple MCP servers."""
+
+    @pytest.mark.parametrize(
+        "mcp_server_config",
+        [
+            {
+                "name": "mcp-oauth",
+                "internal_url": "http://mcp-oauth:8001",
+                "public_url": "http://localhost:8001",
+            },
+            {
+                "name": "mcp-keycloak",
+                "internal_url": "http://mcp-keycloak:8002",
+                "public_url": "http://localhost:8002",
+            },
+            # Add more MCP server configurations as needed:
+            # {
+            #     "name": "mcp-multi-user-basic",
+            #     "internal_url": "http://mcp-multi-user-basic:8000",
+            #     "public_url": "http://localhost:8003",
+            # },
+        ],
+    )
+    async def test_astrolabe_configuration_for_different_servers(
+        self, configure_astrolabe_for_mcp_server, mcp_server_config
+    ):
+        """Test that Astrolabe can be configured for different MCP servers.
+
+        This test verifies that:
+        1. The configure_astrolabe_for_mcp_server fixture successfully configures
+           the Astrolabe app for different MCP server endpoints
+        2. OAuth client credentials are properly generated and stored
+        3. The configuration can be dynamically changed between tests
+        """
+        logger.info(f"Configuring Astrolabe for {mcp_server_config['name']}...")
+
+        # Configure Astrolabe for the specific MCP server
+        credentials = await configure_astrolabe_for_mcp_server(
+            mcp_server_internal_url=mcp_server_config["internal_url"],
+            mcp_server_public_url=mcp_server_config["public_url"],
+        )
+
+        # Verify credentials were returned
+        assert "client_id" in credentials
+        assert "client_secret" in credentials
+        assert credentials["client_id"] == "nextcloudMcpServerUIPublicClient"
+        assert len(credentials["client_secret"]) > 0
+
+        logger.info(
+            f"✓ Astrolabe successfully configured for {mcp_server_config['name']}"
+        )
+        logger.info(f"  Internal URL: {mcp_server_config['internal_url']}")
+        logger.info(f"  Public URL: {mcp_server_config['public_url']}")
+        logger.info(f"  Client ID: {credentials['client_id']}")
+        logger.info(f"  Client Secret: {credentials['client_secret'][:8]}...")
+
+    async def test_astrolabe_reconfiguration(self, configure_astrolabe_for_mcp_server):
+        """Test that Astrolabe can be reconfigured multiple times in the same session.
+
+        This verifies that the OAuth client can be recreated with different
+        settings without conflicts.
+        """
+        # First configuration: mcp-oauth
+        logger.info("First configuration: mcp-oauth")
+        credentials1 = await configure_astrolabe_for_mcp_server(
+            mcp_server_internal_url="http://mcp-oauth:8001",
+            mcp_server_public_url="http://localhost:8001",
+        )
+
+        assert credentials1["client_id"] == "nextcloudMcpServerUIPublicClient"
+
+        # Second configuration: mcp-keycloak (reconfiguration)
+        logger.info("Second configuration: mcp-keycloak (reconfiguration)")
+        credentials2 = await configure_astrolabe_for_mcp_server(
+            mcp_server_internal_url="http://mcp-keycloak:8002",
+            mcp_server_public_url="http://localhost:8002",
+        )
+
+        assert credentials2["client_id"] == "nextcloudMcpServerUIPublicClient"
+
+        # Client secrets should be different (new client created)
+        assert credentials1["client_secret"] != credentials2["client_secret"]
+
+        logger.info("✓ Astrolabe successfully reconfigured without conflicts")
@@ -17,6 +17,7 @@ Architecture:
    MCP Client → Keycloak DCR → Keycloak OAuth → MCP Server → Nextcloud APIs
 """

+import json
 import logging
 import os
 import secrets
@@ -623,7 +624,6 @@ async def test_keycloak_dcr_architecture():
    }

    logger.info("Keycloak DCR Architecture:")
-    import json

    logger.info(json.dumps(architecture, indent=2))

@@ -10,8 +10,14 @@ logger = logging.getLogger(__name__)
 pytestmark = [pytest.mark.integration, pytest.mark.oauth]


-async def test_capture_settings_page(browser):
+async def test_capture_settings_page(browser, configure_astrolabe_for_mcp_server):
    """Capture what's actually rendered on the personal settings page."""
+    # Configure Astrolabe for mcp-oauth server
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-oauth:8001",
+        mcp_server_public_url="http://localhost:8001",
+    )
+
    nextcloud_host = os.getenv("NEXTCLOUD_HOST", "http://localhost:8080")
    username = os.getenv("NEXTCLOUD_USERNAME", "admin")
    password = os.getenv("NEXTCLOUD_PASSWORD", "admin")
@@ -31,7 +37,7 @@ async def test_capture_settings_page(browser):

        # Navigate to settings
        logger.info("Navigating to personal MCP settings...")
-        await page.goto(f"{nextcloud_host}/settings/user/mcp")
+        await page.goto(f"{nextcloud_host}/settings/user/astrolabe")
        await page.wait_for_load_state("networkidle")

        # Capture page content
@@ -46,13 +52,13 @@ async def test_capture_settings_page(browser):
        logger.info(f"Page URL: {page.url}")
        logger.info(f"Page title: {await page.title()}")

-        # Check for key strings
+        # Check for key strings (Vue 3 UI)
        checks = [
-            "Authorize Access",
-            "Authorization Required",
-            "MCP Server",
-            "Sign In Again",
-            "astrolabe",
+            "Enable Semantic Search",  # oauth-required.php authorization button
+            "Service Status",  # personal.php when authorized
+            "Background Sync Access",  # personal.php when authorized
+            "What happens next?",  # oauth-required.php steps
+            "Astrolabe",  # Header
        ]

        for check in checks:
@@ -69,6 +75,15 @@ async def test_capture_settings_page(browser):
        for i, link_text in enumerate(links[:10]):
            logger.info(f"  Link {i}: {link_text}")

+        # Check the Enable Semantic Search button href
+        try:
+            btn = page.locator('a:has-text("Enable Semantic Search")')
+            if await btn.count() > 0:
+                href = await btn.get_attribute("href")
+                logger.info(f"Enable Semantic Search button href: {href}")
+        except Exception as e:
+            logger.warning(f"Could not get button href: {e}")
+
        # Check for error messages
        if "error" in page_content.lower():
            logger.warning("Page contains 'error' keyword")
@@ -44,14 +44,32 @@ async def nc_admin_http_client(nextcloud_credentials):


@pytest.fixture(scope="module")
-async def authorized_nc_session(browser, nextcloud_credentials):
+async def configure_astrolabe_for_tests(configure_astrolabe_for_mcp_server):
+    """Configure Astrolabe to connect to mcp-oauth server before running tests.
+
+    This module-scoped fixture ensures Astrolabe is properly configured
+    for the mcp-oauth server (http://localhost:8001) before any tests run.
+    """
+    logger.info("Configuring Astrolabe for mcp-oauth server...")
+    await configure_astrolabe_for_mcp_server(
+        mcp_server_internal_url="http://mcp-oauth:8001",
+        mcp_server_public_url="http://localhost:8001",
+    )
+    logger.info("✓ Astrolabe configured for mcp-oauth server")
+
+
+@pytest.fixture(scope="module")
+async def authorized_nc_session(
+    browser, nextcloud_credentials, configure_astrolabe_for_tests
+):
    """Module-scoped fixture that logs in and authorizes the NC PHP app once.

    This fixture:
-    1. Creates a browser context
-    2. Logs in to Nextcloud
-    3. Authorizes the MCP Server UI app (if not already authorized)
-    4. Returns the page for use in all tests
+    1. Configures Astrolabe for mcp-oauth server (via configure_astrolabe_for_tests)
+    2. Creates a browser context
+    3. Logs in to Nextcloud
+    4. Authorizes the MCP Server UI app (if not already authorized)
+    5. Returns the page for use in all tests

    The authorization is done once and reused for all tests in this module.
    """
@@ -87,21 +105,26 @@ async def authorized_nc_session(browser, nextcloud_credentials):

        # Step 2: Navigate to personal MCP settings
        logger.info("Navigating to personal MCP settings...")
-        await page.goto(f"{host}/settings/user/mcp")
+        await page.goto(f"{host}/settings/user/astrolabe")
        await page.wait_for_load_state("networkidle")

        page_content = await page.content()

        # Step 3: Check if authorization is needed
-        if "Authorize Access" in page_content or "authorize" in page_content.lower():
+        # Vue 3 UI shows "Enable Semantic Search" when not authorized
+        if (
+            "Enable Semantic Search" in page_content
+            or "What happens next?" in page_content
+        ):
            logger.info("User not authorized yet - initiating OAuth flow...")

-            # Click "Authorize Access" button
+            # Click "Enable Semantic Search" button (Vue 3 template text)
            authorize_selectors = [
-                'button:has-text("Authorize")',
-                'a:has-text("Authorize")',
-                '[href*="oauth/authorize"]',
-                'button:has-text("Connect")',
+                'a:has-text("Enable Semantic Search")',
+                'button:has-text("Enable Semantic Search")',
+                'a:has-text("Sign In Again")',
+                "a.button.primary",
+                '[href*="oauth/login"]',
            ]

            clicked = False
@@ -124,9 +147,17 @@ async def authorized_nc_session(browser, nextcloud_credentials):
            # Wait for page to load after clicking
            await page.wait_for_load_state("networkidle", timeout=10000)
            current_url = page.url
+            logger.info(f"After clicking authorize, current URL: {current_url}")
+
+            # Take screenshot for debugging
+            await page.screenshot(path="/tmp/nc-php-app-after-authorize-click.png")
+            logger.info("Screenshot saved to /tmp/nc-php-app-after-authorize-click.png")

            # Handle OAuth consent if needed
-            if "/apps/oidc/authorize" in current_url:
+            if (
+                "/apps/oidc/authorize" in current_url
+                or "/apps/oidc/consent" in current_url
+            ):
                logger.info("On OIDC authorization page - granting consent...")

                consent_selectors = [
@@ -145,7 +176,7 @@ async def authorized_nc_session(browser, nextcloud_credentials):
                        continue

            # Wait for redirect back to settings
-            await page.wait_for_url(f"{host}/settings/user/mcp", timeout=15000)
+            await page.wait_for_url(f"{host}/settings/user/astrolabe", timeout=15000)
            await page.wait_for_load_state("networkidle")
            logger.info("✓ OAuth authorization completed")

@@ -179,28 +210,32 @@ class TestNcPhpAppOAuth:
        host = authorized_nc_session["host"]

        # Navigate to settings (may already be there)
-        await page.goto(f"{host}/settings/user/mcp")
+        await page.goto(f"{host}/settings/user/astrolabe")
        await page.wait_for_load_state("networkidle")

        page_content = await page.content()

-        # Look for indicators that authorization succeeded
+        # Look for indicators that authorization succeeded (Vue 3 personal.php template)
+        # These must be unique to the authorized state (not found in oauth-required.php)
        success_indicators = [
-            "Connected",
-            "Disconnect",
-            "Server Connection",
-            "Session Information",
-            "MCP Server",
+            "Service Status",
+            "Background Sync Access",
+            "Manage Connection",
+            "Revoke Access",
+            "Service URL",
        ]

-        has_success_indicator = any(
-            indicator in page_content for indicator in success_indicators
-        )
+        found_indicators = [ind for ind in success_indicators if ind in page_content]
+        has_success_indicator = len(found_indicators) > 0
+
+        # Always take screenshot for debugging
+        screenshot_path = "/tmp/nc-php-app-auth-check.png"
+        await page.screenshot(path=screenshot_path)
+        logger.info(f"Authorization check screenshot: {screenshot_path}")
+        logger.info(f"Found success indicators: {found_indicators}")

        if not has_success_indicator:
-            screenshot_path = "/tmp/nc-php-app-auth-check.png"
-            await page.screenshot(path=screenshot_path)
-            logger.error(f"Authorization check failed. Screenshot: {screenshot_path}")
+            logger.error("Authorization check failed.")

        assert has_success_indicator, "Settings page should show user is authorized"
        logger.info("✓ Authorization verification passed")
@@ -214,7 +249,7 @@ class TestNcPhpAppOAuth:
        page = authorized_nc_session["page"]
        host = authorized_nc_session["host"]

-        await page.goto(f"{host}/settings/user/mcp")
+        await page.goto(f"{host}/settings/user/astrolabe")
        await page.wait_for_load_state("networkidle")

        page_content = await page.content()
@@ -225,12 +260,12 @@ class TestNcPhpAppOAuth:
        logger.info(f"Screenshot saved: {screenshot_path}")
        logger.info(f"Page content excerpt: {page_content[:1000]}")

-        # Verify session information is visible - these are the actual labels from template
+        # Verify session information is visible (Vue 3 personal.php template)
        session_indicators = [
-            "Server Connection",
-            "Session Information",
-            "Connection Management",
-            "MCP Server",
+            "Service Status",
+            "Service URL",
+            "Version",
+            "Background Sync Access",
        ]

        found_indicators = [ind for ind in session_indicators if ind in page_content]
@@ -252,17 +287,17 @@ class TestNcPhpAppOAuth:
        host = authorized_nc_session["host"]

        # Check personal settings page shows server status
-        await page.goto(f"{host}/settings/user/mcp")
+        await page.goto(f"{host}/settings/user/astrolabe")
        await page.wait_for_load_state("networkidle")

        page_content = await page.content()

-        # Look for data that comes from management API or template structure
+        # Look for data that comes from management API or template structure (Vue 3)
        api_indicators = [
-            "Server Connection",  # Section header
-            "Server URL",  # Server info
-            "Connection Management",  # Connection section
-            "Vector Visualization",  # Vector sync section
+            "Service Status",  # Section header
+            "Service URL",  # Server info from API
+            "Version",  # Server version from management API
+            "Semantic Search",  # Vector sync status
        ]

        found_api_data = [ind for ind in api_indicators if ind in page_content]
@@ -280,23 +315,24 @@ class TestNcPhpAppOAuth:
        page = authorized_nc_session["page"]
        host = authorized_nc_session["host"]

-        await page.goto(f"{host}/settings/admin/mcp")
+        await page.goto(f"{host}/settings/admin/astrolabe")
        await page.wait_for_load_state("networkidle")

        page_content = await page.content()

-        # Admin page should show server status
+        # Admin page should show server status (Vue 3 AdminSettings.vue)
        admin_indicators = [
-            "MCP Server",
-            "Server Status",
+            "Astrolabe",
+            "Service Status",
            "Version",
+            "Semantic Search",
        ]

        found_indicators = [ind for ind in admin_indicators if ind in page_content]

-        # Admin page should at least show the MCP Server header
-        assert "MCP Server" in page_content or "mcp" in page_content.lower(), (
-            "Admin settings page should show MCP Server section"
+        # Admin page should at least show the Astrolabe header or Service Status
+        assert "Astrolabe" in page_content or "Service Status" in page_content, (
+            "Admin settings page should show Astrolabe section"
        )

        logger.info(f"✓ Admin settings page verified - found: {found_indicators}")
@@ -337,13 +373,13 @@ class TestNcPhpAppDisconnect:
            await page.wait_for_url(f"{host}/apps/dashboard/", timeout=10000)

            # Navigate to personal settings
-            await page.goto(f"{host}/settings/user/mcp")
+            await page.goto(f"{host}/settings/user/astrolabe")
            await page.wait_for_load_state("networkidle")

            page_content = await page.content()

-            # Check if user is authorized
-            if "Disconnect" not in page_content:
+            # Check if user is authorized (Vue 3 personal.php shows Disconnect/Revoke when authorized)
+            if "Disconnect" not in page_content and "Revoke Access" not in page_content:
                pytest.skip("User not authorized - cannot test disconnect")

            # Click disconnect button
@@ -366,10 +402,10 @@ class TestNcPhpAppDisconnect:
            # Wait for page reload
            await page.wait_for_load_state("networkidle")

-            # Verify we're back to "Authorize Access" state
+            # Verify we're back to "Enable Semantic Search" state (Vue 3 oauth-required.php)
            page_content = await page.content()
-            assert "Authorize" in page_content, (
-                "Settings page should show 'Authorize Access' after disconnect"
+            assert "Enable Semantic Search" in page_content, (
+                "Settings page should show 'Enable Semantic Search' after disconnect"
            )

            logger.info("✓ Disconnect flow test passed")
@@ -11,13 +11,15 @@ Note: Tests use JWT OAuth tokens because scopes are embedded in the token payloa
 enabling efficient scope-based tool filtering without additional API calls.
 """

+import logging
+
+import httpx
 import pytest


@pytest.mark.integration
 async def test_prm_endpoint():
    """Test that the Protected Resource Metadata endpoint returns correct data."""
-    import httpx

    # Test the PRM endpoint directly (RFC 9728 - path includes /mcp resource)
    async with httpx.AsyncClient() as client:
@@ -60,7 +62,6 @@ async def test_basicauth_shows_all_tools(nc_mcp_client):
@pytest.mark.integration
 async def test_read_only_token_filters_write_tools(nc_mcp_oauth_client_read_only):
    """Test that a token with only read scopes filters out write tools."""
-    import logging

    logger = logging.getLogger(__name__)

@@ -109,7 +110,6 @@ async def test_read_only_token_filters_write_tools(nc_mcp_oauth_client_read_only
@pytest.mark.integration
 async def test_write_only_token_filters_read_tools(nc_mcp_oauth_client_write_only):
    """Test that a token with only write scopes filters out read tools."""
-    import logging

    logger = logging.getLogger(__name__)

@@ -158,7 +158,6 @@ async def test_write_only_token_filters_read_tools(nc_mcp_oauth_client_write_onl
@pytest.mark.integration
 async def test_full_access_token_shows_all_tools(nc_mcp_oauth_client_full_access):
    """Test that a token with both read and write scopes scopes can see all tools."""
-    import logging

    logger = logging.getLogger(__name__)

@@ -402,7 +401,6 @@ async def test_jwt_with_no_custom_scopes_returns_zero_tools(
    - OAuth provisioning tools (requiring only 'openid') remain visible
      so users can provision Nextcloud access after authentication
    """
-    import logging

    logger = logging.getLogger(__name__)

@@ -442,7 +440,6 @@ async def test_jwt_consent_scenarios_read_only(nc_mcp_oauth_client_read_only):
    Simulates user granting only read permission during OAuth consent.
    Expected: Should see read tools but not write tools.
    """
-    import logging

    logger = logging.getLogger(__name__)

@@ -480,7 +477,6 @@ async def test_jwt_consent_scenarios_write_only(nc_mcp_oauth_client_write_only):
    Simulates user granting only write permission during OAuth consent.
    Expected: Should see write tools but not read-only tools.
    """
-    import logging

    logger = logging.getLogger(__name__)

@@ -518,7 +514,6 @@ async def test_jwt_consent_scenarios_full_access(nc_mcp_oauth_client_full_access
    Simulates user granting both permissions during OAuth consent.
    Expected: Should see all 90+ tools (both read and write).
    """
-    import logging

    logger = logging.getLogger(__name__)

@@ -6,10 +6,12 @@ Tests the critical token exchange pattern that separates:
 """

 import os
+import tempfile
 from unittest.mock import AsyncMock, MagicMock, patch

 import jwt
 import pytest
+from cryptography.fernet import Fernet

 from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
@@ -21,9 +23,6 @@ pytestmark = pytest.mark.unit
@pytest.fixture
 async def token_storage():
    """Create test token storage."""
-    import tempfile
-
-    from cryptography.fernet import Fernet

    # Generate valid Fernet key
    encryption_key = Fernet.generate_key()
@@ -1,5 +1,6 @@
 """Integration tests for Calendar VTODO (task) MCP tools."""

+import json
 import logging
 from datetime import datetime, timedelta

@@ -41,7 +42,6 @@ async def test_mcp_todo_complete_workflow(

        # Extract UID from the result
        result_data = create_result.content[0].text
-        import json

        result_json = json.loads(result_data)
        todo_uid = result_json["uid"]
@@ -156,7 +156,6 @@ async def test_mcp_list_todos_with_filters(
            {"calendar_name": calendar_name, "status": "NEEDS-ACTION"},
        )
        assert result.isError is False
-        import json

        data = json.loads(result.content[0].text)
        needs_action_todos = [t for t in data["todos"] if t["uid"] in created_uids]
@@ -253,8 +252,6 @@ async def test_mcp_search_todos_across_calendars(
        )
        assert search_result.isError is False

-        import json
-
        data = json.loads(search_result.content[0].text)
        assert "todos" in data

@@ -388,8 +385,6 @@ async def test_mcp_todo_with_dates(
        )
        assert create_result.isError is False

-        import json
-
        result_data = json.loads(create_result.content[0].text)
        todo_uid = result_data["uid"]

@@ -432,8 +427,6 @@ async def test_mcp_todo_categories(
        )
        assert create_result.isError is False

-        import json
-
        result_data = json.loads(create_result.content[0].text)
        todo_uid = result_data["uid"]

@@ -0,0 +1,241 @@
+"""Unit tests for BasicAuthMiddleware."""
+
+import base64
+
+import pytest
+
+from nextcloud_mcp_server.app import BasicAuthMiddleware
+
+
+class MockApp:
+    """Mock ASGI app for testing middleware."""
+
+    def __init__(self):
+        self.called = False
+        self.received_scope = None
+
+    async def __call__(self, scope, receive, send):
+        self.called = True
+        self.received_scope = scope
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_valid_credentials():
+    """Test that middleware correctly extracts valid BasicAuth credentials."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    credentials = base64.b64encode(b"admin:password123").decode("utf-8")
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Basic {credentials}".encode())],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    assert "state" in scope
+    assert "basic_auth" in scope["state"]
+    assert scope["state"]["basic_auth"]["username"] == "admin"
+    assert scope["state"]["basic_auth"]["password"] == "password123"
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_password_with_colon():
+    """Test that middleware handles passwords containing colons."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    # Password contains colon - should split on first colon only
+    credentials = base64.b64encode(b"user:pass:word:123").decode("utf-8")
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Basic {credentials}".encode())],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert scope["state"]["basic_auth"]["username"] == "user"
+    assert scope["state"]["basic_auth"]["password"] == "pass:word:123"
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_invalid_base64():
+    """Test that middleware handles invalid base64 encoding gracefully."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", b"Basic INVALID_BASE64!!!")],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    # Should not have basic_auth in state due to error
+    assert "basic_auth" not in scope.get("state", {})
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_missing_authorization_header():
+    """Test that middleware handles missing Authorization header."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    scope = {
+        "type": "http",
+        "headers": [],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    # Should not have basic_auth in state
+    assert "basic_auth" not in scope.get("state", {})
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_wrong_auth_scheme():
+    """Test that middleware ignores non-Basic auth schemes."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", b"Bearer some_token")],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    # Should not have basic_auth in state
+    assert "basic_auth" not in scope.get("state", {})
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_malformed_credentials():
+    """Test that middleware handles credentials without colon separator."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    # Credentials without colon separator
+    credentials = base64.b64encode(b"username_no_password").decode("utf-8")
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Basic {credentials}".encode())],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    # Should not have basic_auth in state due to error
+    assert "basic_auth" not in scope.get("state", {})
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_non_http_scope():
+    """Test that middleware passes through non-HTTP scopes unchanged."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    scope = {
+        "type": "websocket",
+        "headers": [(b"authorization", b"Basic dXNlcjpwYXNz")],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    # Should not process websocket scopes
+    assert "state" not in scope
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_preserves_existing_state():
+    """Test that middleware preserves existing state data."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    credentials = base64.b64encode(b"user:pass").decode("utf-8")
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Basic {credentials}".encode())],
+        "state": {"existing_key": "existing_value"},
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    assert scope["state"]["existing_key"] == "existing_value"
+    assert scope["state"]["basic_auth"]["username"] == "user"
+    assert scope["state"]["basic_auth"]["password"] == "pass"
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_empty_password():
+    """Test that middleware handles empty passwords."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    credentials = base64.b64encode(b"user:").decode("utf-8")
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Basic {credentials}".encode())],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    assert scope["state"]["basic_auth"]["username"] == "user"
+    assert scope["state"]["basic_auth"]["password"] == ""
+
+
+@pytest.mark.unit
+async def test_basic_auth_middleware_unicode_credentials():
+    """Test that middleware handles Unicode characters in credentials."""
+    # Arrange
+    mock_app = MockApp()
+    middleware = BasicAuthMiddleware(mock_app)
+
+    # Username and password with Unicode characters
+    credentials = base64.b64encode("üser:pässwörd".encode("utf-8")).decode("utf-8")
+    scope = {
+        "type": "http",
+        "headers": [(b"authorization", f"Basic {credentials}".encode())],
+    }
+
+    # Act
+    await middleware(scope, None, None)  # type: ignore[arg-type]
+
+    # Assert
+    assert mock_app.called
+    assert scope["state"]["basic_auth"]["username"] == "üser"
+    assert scope["state"]["basic_auth"]["password"] == "pässwörd"
@@ -1,5 +1,6 @@
 """Tests for configuration validation."""

+import logging
 import os
 from unittest.mock import patch

@@ -48,7 +49,6 @@ class TestQdrantConfigValidation:

    def test_api_key_warning_in_local_mode(self, caplog):
        """Test that API key in local mode triggers warning."""
-        import logging

        caplog.set_level(logging.WARNING, logger="nextcloud_mcp_server.config")
        Settings(
@@ -59,7 +59,6 @@ class TestQdrantConfigValidation:

    def test_api_key_no_warning_in_network_mode(self, caplog):
        """Test that API key in network mode doesn't trigger warning."""
-        import logging

        caplog.set_level(logging.WARNING, logger="nextcloud_mcp_server.config")
        Settings(
@@ -206,7 +205,6 @@ class TestChunkConfigValidation:

    def test_small_chunk_size_warning(self, caplog):
        """Test that chunk size < 512 triggers warning."""
-        import logging

        caplog.set_level(logging.WARNING, logger="nextcloud_mcp_server.config")
        Settings(
@@ -221,7 +219,6 @@ class TestChunkConfigValidation:

    def test_reasonable_chunk_size_no_warning(self, caplog):
        """Test that chunk size >= 512 doesn't trigger warning."""
-        import logging

        caplog.set_level(logging.WARNING, logger="nextcloud_mcp_server.config")
        Settings(
@@ -0,0 +1,992 @@
+"""Unit tests for configuration validation and mode detection.
+
+Tests cover:
+- Mode detection logic
+- Configuration validation for each mode
+- Error message generation
+- Edge cases and boundary conditions
+"""
+
+import os
+from unittest.mock import patch
+
+from nextcloud_mcp_server.config import Settings
+from nextcloud_mcp_server.config_validators import (
+    AuthMode,
+    detect_auth_mode,
+    get_mode_summary,
+    validate_configuration,
+)
+
+
+class TestModeDetection:
+    """Test auth mode detection from configuration."""
+
+    def test_smithery_mode_detection(self):
+        """Test Smithery mode is detected from environment variable."""
+        settings = Settings()
+
+        with patch.dict(os.environ, {"SMITHERY_DEPLOYMENT": "true"}):
+            mode = detect_auth_mode(settings)
+            assert mode == AuthMode.SMITHERY_STATELESS
+
+    def test_token_exchange_mode_detection(self):
+        """Test token exchange mode is detected."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_token_exchange=True,
+        )
+
+        mode = detect_auth_mode(settings)
+        assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+
+    def test_multi_user_basic_mode_detection(self):
+        """Test multi-user BasicAuth mode is detected."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_multi_user_basic_auth=True,
+        )
+
+        mode = detect_auth_mode(settings)
+        assert mode == AuthMode.MULTI_USER_BASIC
+
+    def test_single_user_basic_mode_detection(self):
+        """Test single-user BasicAuth mode is detected."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode = detect_auth_mode(settings)
+        assert mode == AuthMode.SINGLE_USER_BASIC
+
+    def test_oauth_single_audience_default(self):
+        """Test OAuth single-audience is default mode."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+        )
+
+        mode = detect_auth_mode(settings)
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+
+    def test_mode_priority_smithery_over_all(self):
+        """Test Smithery mode has highest priority."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            enable_token_exchange=True,
+            enable_multi_user_basic_auth=True,
+        )
+
+        with patch.dict(os.environ, {"SMITHERY_DEPLOYMENT": "true"}):
+            mode = detect_auth_mode(settings)
+            assert mode == AuthMode.SMITHERY_STATELESS
+
+    def test_mode_priority_token_exchange_over_basic(self):
+        """Test token exchange has priority over BasicAuth."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            enable_token_exchange=True,
+        )
+
+        mode = detect_auth_mode(settings)
+        assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+
+
+class TestSingleUserBasicValidation:
+    """Test validation for single-user BasicAuth mode."""
+
+    def test_valid_minimal_config(self):
+        """Test valid minimal single-user BasicAuth config."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.SINGLE_USER_BASIC
+        assert len(errors) == 0
+
+    def test_valid_with_vector_sync(self):
+        """Test valid config with vector sync enabled."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            vector_sync_enabled=True,
+            qdrant_location=":memory:",
+            ollama_base_url="http://ollama:11434",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.SINGLE_USER_BASIC
+        assert len(errors) == 0
+
+    def test_missing_required_host(self):
+        """Test error when NEXTCLOUD_HOST is missing."""
+        settings = Settings(
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.SINGLE_USER_BASIC
+        assert any("nextcloud_host" in err.lower() for err in errors)
+
+    def test_missing_required_username(self):
+        """Test that partial credentials fall back to OAuth mode."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_password="password",  # Password without username
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # Mode detection requires BOTH username AND password for single-user BasicAuth
+        # If only one is present, it defaults to OAuth single-audience
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+        # In OAuth mode, having a password set is forbidden
+        assert any("nextcloud_password" in err.lower() for err in errors)
+
+    def test_missing_required_password(self):
+        """Test that partial credentials fall back to OAuth mode."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",  # Username without password
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # Mode detection requires BOTH username AND password for single-user BasicAuth
+        # If only one is present, it defaults to OAuth single-audience
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+        # In OAuth mode, having a username set is forbidden
+        assert any("nextcloud_username" in err.lower() for err in errors)
+
+    def test_forbidden_multi_user_basic_auth(self):
+        """Test error when ENABLE_MULTI_USER_BASIC_AUTH is set."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            enable_multi_user_basic_auth=True,
+        )
+
+        # Note: This will detect as MULTI_USER_BASIC due to priority
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.MULTI_USER_BASIC
+        # It will fail multi-user validation because username/password are forbidden
+        assert len(errors) > 0
+
+    def test_forbidden_token_exchange(self):
+        """Test error when ENABLE_TOKEN_EXCHANGE is set."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            enable_token_exchange=True,
+        )
+
+        # Note: This will detect as OAUTH_TOKEN_EXCHANGE due to priority
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+        # It will fail OAuth validation
+
+    def test_vector_sync_without_embedding_provider_uses_fallback(self):
+        """Test that vector sync works with Simple provider fallback (no config needed)."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            vector_sync_enabled=True,
+            qdrant_location=":memory:",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.SINGLE_USER_BASIC
+        # Should pass - Simple provider is always available as fallback
+        assert len(errors) == 0
+
+
+class TestMultiUserBasicValidation:
+    """Test validation for multi-user BasicAuth mode."""
+
+    def test_valid_minimal_config(self):
+        """Test valid minimal multi-user BasicAuth config."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_multi_user_basic_auth=True,
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.MULTI_USER_BASIC
+        assert len(errors) == 0
+
+    def test_valid_with_offline_access(self):
+        """Test valid config with offline access enabled."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_multi_user_basic_auth=True,
+            enable_offline_access=True,
+            oidc_client_id="test-client",
+            oidc_client_secret="test-secret",
+            token_encryption_key="test-key-" + "a" * 32,
+            token_storage_db="/tmp/tokens.db",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.MULTI_USER_BASIC
+        assert len(errors) == 0
+
+    def test_missing_required_host(self):
+        """Test error when NEXTCLOUD_HOST is missing."""
+        settings = Settings(
+            enable_multi_user_basic_auth=True,
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.MULTI_USER_BASIC
+        assert any("nextcloud_host" in err.lower() for err in errors)
+
+    def test_forbidden_username_password(self):
+        """Test error when NEXTCLOUD_USERNAME/PASSWORD are set."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+            enable_multi_user_basic_auth=True,
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # Multi-user BasicAuth has higher priority than single-user in detection
+        # (explicit flags come before credentials)
+        assert mode == AuthMode.MULTI_USER_BASIC
+        # Should report errors for forbidden username/password
+        assert any("nextcloud_username" in err.lower() for err in errors)
+        assert any("nextcloud_password" in err.lower() for err in errors)
+
+    def test_offline_access_missing_oauth_credentials(self):
+        """Test that offline access works without OAuth credentials (will use DCR)."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_multi_user_basic_auth=True,
+            enable_offline_access=True,
+            token_encryption_key="test-key-" + "a" * 32,
+            token_storage_db="/tmp/tokens.db",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.MULTI_USER_BASIC
+        # No errors - DCR will be used as fallback (consistent with OAuth modes)
+        assert len(errors) == 0
+
+    def test_offline_access_missing_encryption_key(self):
+        """Test error when offline access enabled but encryption key missing."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_multi_user_basic_auth=True,
+            enable_offline_access=True,
+            oidc_client_id="test-client",
+            oidc_client_secret="test-secret",
+            token_storage_db="/tmp/tokens.db",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.MULTI_USER_BASIC
+        assert any("token_encryption_key" in err.lower() for err in errors)
+
+    def test_vector_sync_auto_enables_background_ops_in_multi_user_mode(self):
+        """Test vector sync automatically enables background operations in multi-user mode (ADR-021)."""
+        # Before ADR-021: This would have failed validation (required explicit ENABLE_OFFLINE_ACCESS)
+        # After ADR-021: vector_sync_enabled auto-enables background operations
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "ENABLE_MULTI_USER_BASIC_AUTH": "true",
+                "VECTOR_SYNC_ENABLED": "true",  # Using old name for backward compat test
+                "QDRANT_LOCATION": ":memory:",
+                "OLLAMA_BASE_URL": "http://ollama:11434",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+                "NEXTCLOUD_OIDC_CLIENT_ID": "test-client-id",
+                "NEXTCLOUD_OIDC_CLIENT_SECRET": "test-client-secret",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode, errors = validate_configuration(settings)
+
+            assert mode == AuthMode.MULTI_USER_BASIC
+            # Should have no errors - background operations auto-enabled
+            assert len(errors) == 0
+            # Verify background operations were auto-enabled
+            assert settings.enable_offline_access is True
+
+
+class TestOAuthSingleAudienceValidation:
+    """Test validation for OAuth single-audience mode."""
+
+    def test_valid_minimal_config(self):
+        """Test valid minimal OAuth single-audience config."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+        assert len(errors) == 0
+
+    def test_valid_with_static_credentials(self):
+        """Test valid config with static OAuth credentials."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            oidc_client_id="test-client",
+            oidc_client_secret="test-secret",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+        assert len(errors) == 0
+
+    def test_valid_with_offline_access(self):
+        """Test valid config with offline access."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            oidc_client_id="test-client",
+            oidc_client_secret="test-secret",
+            enable_offline_access=True,
+            token_encryption_key="test-key-" + "a" * 32,
+            token_storage_db="/tmp/tokens.db",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+        assert len(errors) == 0
+
+    def test_forbidden_username_password(self):
+        """Test that username/password trigger single-user mode instead."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # This should detect as SINGLE_USER_BASIC
+        assert mode == AuthMode.SINGLE_USER_BASIC
+
+    def test_offline_access_missing_encryption_key(self):
+        """Test error when offline access enabled but encryption key missing."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_offline_access=True,
+            token_storage_db="/tmp/tokens.db",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+        assert any("token_encryption_key" in err.lower() for err in errors)
+
+    def test_vector_sync_auto_enables_background_ops_in_oauth_mode(self):
+        """Test vector sync automatically enables background operations in OAuth mode (ADR-021)."""
+        # Before ADR-021: This would have failed validation (required explicit ENABLE_OFFLINE_ACCESS)
+        # After ADR-021: vector_sync_enabled auto-enables background operations in multi-user modes
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "VECTOR_SYNC_ENABLED": "true",
+                "QDRANT_LOCATION": ":memory:",
+                "OLLAMA_BASE_URL": "http://ollama:11434",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+                # Note: No username/password = OAuth mode
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode, errors = validate_configuration(settings)
+
+            assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+            # Should have no errors - background operations auto-enabled
+            assert len(errors) == 0
+            # Verify background operations were auto-enabled
+            assert settings.enable_offline_access is True
+
+
+class TestOAuthTokenExchangeValidation:
+    """Test validation for OAuth token exchange mode."""
+
+    def test_valid_minimal_config(self):
+        """Test valid minimal OAuth token exchange config."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_token_exchange=True,
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+        assert len(errors) == 0
+
+    def test_valid_with_credentials(self):
+        """Test valid config with OAuth credentials."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_token_exchange=True,
+            oidc_client_id="test-client",
+            oidc_client_secret="test-secret",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+        assert len(errors) == 0
+
+    def test_forbidden_username_password(self):
+        """Test error when username/password are set."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+            enable_token_exchange=True,
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+        assert any("nextcloud_username" in err.lower() for err in errors)
+        assert any("nextcloud_password" in err.lower() for err in errors)
+
+
+class TestSmitheryValidation:
+    """Test validation for Smithery stateless mode."""
+
+    def test_valid_empty_config(self):
+        """Test valid empty config for Smithery mode."""
+        settings = Settings()
+
+        with patch.dict(os.environ, {"SMITHERY_DEPLOYMENT": "true"}):
+            mode, errors = validate_configuration(settings)
+
+            assert mode == AuthMode.SMITHERY_STATELESS
+            assert len(errors) == 0
+
+    def test_forbidden_nextcloud_host(self):
+        """Test error when NEXTCLOUD_HOST is set."""
+        settings = Settings(
+            nextcloud_host="http://localhost",
+        )
+
+        with patch.dict(os.environ, {"SMITHERY_DEPLOYMENT": "true"}):
+            mode, errors = validate_configuration(settings)
+
+            assert mode == AuthMode.SMITHERY_STATELESS
+            assert any("nextcloud_host" in err.lower() for err in errors)
+
+    def test_forbidden_credentials(self):
+        """Test error when credentials are set."""
+        settings = Settings(
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        with patch.dict(os.environ, {"SMITHERY_DEPLOYMENT": "true"}):
+            mode, errors = validate_configuration(settings)
+
+            assert mode == AuthMode.SMITHERY_STATELESS
+            assert any("nextcloud_username" in err.lower() for err in errors)
+
+    def test_forbidden_vector_sync(self):
+        """Test error when vector sync is enabled."""
+        settings = Settings(
+            vector_sync_enabled=True,
+        )
+
+        with patch.dict(os.environ, {"SMITHERY_DEPLOYMENT": "true"}):
+            mode, errors = validate_configuration(settings)
+
+            assert mode == AuthMode.SMITHERY_STATELESS
+            assert any("vector_sync_enabled" in err.lower() for err in errors)
+
+
+class TestModeSummary:
+    """Test mode summary generation."""
+
+    def test_single_user_basic_summary(self):
+        """Test summary for single-user BasicAuth mode."""
+        summary = get_mode_summary(AuthMode.SINGLE_USER_BASIC)
+
+        assert "single_user_basic" in summary
+        assert "NEXTCLOUD_HOST" in summary
+        assert "NEXTCLOUD_USERNAME" in summary
+        assert "NEXTCLOUD_PASSWORD" in summary
+        assert "VECTOR_SYNC_ENABLED" in summary
+
+    def test_smithery_summary(self):
+        """Test summary for Smithery mode."""
+        summary = get_mode_summary(AuthMode.SMITHERY_STATELESS)
+
+        assert "smithery" in summary
+        assert "session" in summary.lower()
+        assert "(none" in summary  # No required config
+
+    def test_oauth_token_exchange_summary(self):
+        """Test summary for OAuth token exchange mode."""
+        summary = get_mode_summary(AuthMode.OAUTH_TOKEN_EXCHANGE)
+
+        assert "oauth_exchange" in summary
+        assert "ENABLE_TOKEN_EXCHANGE" in summary
+        assert "RFC 8693" in summary
+
+
+class TestEdgeCases:
+    """Test edge cases and boundary conditions."""
+
+    def test_empty_string_treated_as_missing(self):
+        """Test that empty strings are treated as missing values."""
+        settings = Settings(
+            nextcloud_host="",  # Empty string
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # Should fail because nextcloud_host is effectively missing
+        assert any("nextcloud_host" in err.lower() for err in errors)
+
+    def test_whitespace_treated_as_missing(self):
+        """Test that whitespace-only strings are treated as missing."""
+        settings = Settings(
+            nextcloud_host="   ",  # Whitespace only
+            nextcloud_username="admin",
+            nextcloud_password="password",
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # Should fail because nextcloud_host is effectively missing
+        assert any("nextcloud_host" in err.lower() for err in errors)
+
+    def test_multiple_errors_reported(self):
+        """Test that multiple errors are all reported."""
+        settings = Settings(
+            # Missing all required fields for single-user BasicAuth
+        )
+
+        mode, errors = validate_configuration(settings)
+
+        # Should have errors for missing host (OAuth mode is default)
+        assert len(errors) > 0
+
+
+class TestConfigurationConsolidation:
+    """Test ADR-021 configuration consolidation and backward compatibility.
+
+    Tests verify:
+    - New variable names work (ENABLE_SEMANTIC_SEARCH, ENABLE_BACKGROUND_OPERATIONS)
+    - Old variable names still work (VECTOR_SYNC_ENABLED, ENABLE_OFFLINE_ACCESS)
+    - Deprecation warnings are logged
+    - Auto-enablement of background operations in multi-user modes
+    """
+
+    def test_new_semantic_search_variable_name(self):
+        """Test ENABLE_SEMANTIC_SEARCH (new name) works correctly."""
+        with patch.dict(
+            os.environ,
+            {
+                "ENABLE_SEMANTIC_SEARCH": "true",
+                "QDRANT_LOCATION": ":memory:",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            assert settings.vector_sync_enabled is True
+
+    def test_old_vector_sync_variable_name_backward_compat(self):
+        """Test VECTOR_SYNC_ENABLED (old name) still works for backward compatibility."""
+        with patch.dict(
+            os.environ,
+            {
+                "VECTOR_SYNC_ENABLED": "true",
+                "QDRANT_LOCATION": ":memory:",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            assert settings.vector_sync_enabled is True
+
+    def test_new_background_operations_variable_name(self):
+        """Test ENABLE_BACKGROUND_OPERATIONS (new name) works correctly."""
+        with patch.dict(
+            os.environ,
+            {
+                "ENABLE_BACKGROUND_OPERATIONS": "true",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            assert settings.enable_offline_access is True
+
+    def test_old_offline_access_variable_name_backward_compat(self):
+        """Test ENABLE_OFFLINE_ACCESS (old name) still works for backward compatibility."""
+        with patch.dict(
+            os.environ,
+            {
+                "ENABLE_OFFLINE_ACCESS": "true",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            assert settings.enable_offline_access is True
+
+    def test_semantic_search_auto_enables_background_ops_in_oauth_mode(self):
+        """Test ENABLE_SEMANTIC_SEARCH automatically enables background operations in OAuth mode."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "ENABLE_SEMANTIC_SEARCH": "true",
+                "QDRANT_LOCATION": ":memory:",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+                # Note: No NEXTCLOUD_USERNAME/PASSWORD = OAuth mode
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+
+            # Semantic search enabled
+            assert settings.vector_sync_enabled is True
+
+            # Background operations auto-enabled (even though not explicitly set)
+            assert settings.enable_offline_access is True
+
+    def test_semantic_search_does_not_auto_enable_in_single_user_mode(self):
+        """Test ENABLE_SEMANTIC_SEARCH does NOT auto-enable background ops in single-user mode."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "NEXTCLOUD_USERNAME": "admin",
+                "NEXTCLOUD_PASSWORD": "password",
+                "ENABLE_SEMANTIC_SEARCH": "true",
+                "QDRANT_LOCATION": ":memory:",
+                # Note: Username/password set = single-user BasicAuth mode
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+
+            # Semantic search enabled
+            assert settings.vector_sync_enabled is True
+
+            # Background operations NOT auto-enabled (not needed in single-user mode)
+            assert settings.enable_offline_access is False
+
+    def test_explicit_background_ops_still_works(self):
+        """Test explicitly setting ENABLE_BACKGROUND_OPERATIONS works even without semantic search."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "ENABLE_BACKGROUND_OPERATIONS": "true",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+                # Note: No semantic search enabled
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+
+            # Semantic search NOT enabled
+            assert settings.vector_sync_enabled is False
+
+            # Background operations explicitly enabled
+            assert settings.enable_offline_access is True
+
+    def test_both_old_and_new_semantic_search_names_prefers_new(self):
+        """Test setting both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED uses new name."""
+        with patch.dict(
+            os.environ,
+            {
+                "ENABLE_SEMANTIC_SEARCH": "true",
+                "VECTOR_SYNC_ENABLED": "false",  # Old name says false
+                "QDRANT_LOCATION": ":memory:",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+
+            # Should use new name value (true)
+            assert settings.vector_sync_enabled is True
+
+    def test_both_old_and_new_background_ops_names_prefers_new(self):
+        """Test setting both ENABLE_BACKGROUND_OPERATIONS and ENABLE_OFFLINE_ACCESS uses new name."""
+        with patch.dict(
+            os.environ,
+            {
+                "ENABLE_BACKGROUND_OPERATIONS": "true",
+                "ENABLE_OFFLINE_ACCESS": "false",  # Old name says false
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+
+            # Should use new name value (true)
+            assert settings.enable_offline_access is True
+
+    def test_validation_no_longer_requires_both_variables(self):
+        """Test validation no longer requires explicit ENABLE_OFFLINE_ACCESS when semantic search enabled."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "ENABLE_MULTI_USER_BASIC_AUTH": "true",
+                "ENABLE_SEMANTIC_SEARCH": "true",
+                "QDRANT_LOCATION": ":memory:",
+                "TOKEN_ENCRYPTION_KEY": "test-key",
+                "TOKEN_STORAGE_DB": "/tmp/test.db",
+                # OAuth credentials required for app password retrieval (when background ops enabled)
+                "NEXTCLOUD_OIDC_CLIENT_ID": "test-client-id",
+                "NEXTCLOUD_OIDC_CLIENT_SECRET": "test-client-secret",
+                # Note: ENABLE_OFFLINE_ACCESS not set - should auto-enable
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode, errors = validate_configuration(settings)
+
+            # Should have no validation errors
+            # (Previously would have required explicit ENABLE_OFFLINE_ACCESS)
+            assert len(errors) == 0
+            assert mode == AuthMode.MULTI_USER_BASIC
+            # Verify background operations were auto-enabled
+            assert settings.enable_offline_access is True
+
+
+class TestExplicitModeSelection:
+    """Test ADR-021 explicit mode selection via MCP_DEPLOYMENT_MODE.
+
+    Tests verify:
+    - Explicit mode selection works for all modes
+    - Invalid mode names raise ValueError
+    - Explicit mode takes precedence over auto-detection
+    """
+
+    def test_explicit_single_user_basic_mode(self):
+        """Test explicit single_user_basic mode selection."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "single_user_basic",
+                "NEXTCLOUD_USERNAME": "admin",
+                "NEXTCLOUD_PASSWORD": "password",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.SINGLE_USER_BASIC
+
+    def test_explicit_multi_user_basic_mode(self):
+        """Test explicit multi_user_basic mode selection."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "multi_user_basic",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.MULTI_USER_BASIC
+
+    def test_explicit_oauth_single_audience_mode(self):
+        """Test explicit oauth_single_audience mode selection."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "oauth_single_audience",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+
+    def test_explicit_oauth_token_exchange_mode(self):
+        """Test explicit oauth_token_exchange mode selection."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "oauth_token_exchange",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.OAUTH_TOKEN_EXCHANGE
+
+    def test_explicit_smithery_mode(self):
+        """Test explicit smithery mode selection."""
+        with patch.dict(
+            os.environ,
+            {
+                "MCP_DEPLOYMENT_MODE": "smithery",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.SMITHERY_STATELESS
+
+    def test_invalid_deployment_mode_raises_error(self):
+        """Test invalid MCP_DEPLOYMENT_MODE raises ValueError."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "invalid_mode",
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+
+            # Should raise ValueError with clear message
+            try:
+                detect_auth_mode(settings)
+                assert False, "Should have raised ValueError"
+            except ValueError as e:
+                assert "Invalid MCP_DEPLOYMENT_MODE" in str(e)
+                assert "invalid_mode" in str(e)
+                assert "Valid values:" in str(e)
+
+    def test_explicit_mode_overrides_auto_detection(self):
+        """Test explicit mode takes precedence over auto-detection."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "NEXTCLOUD_USERNAME": "admin",  # Would auto-detect as single_user_basic
+                "NEXTCLOUD_PASSWORD": "password",
+                "MCP_DEPLOYMENT_MODE": "oauth_single_audience",  # Explicit override
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            # Should use explicit mode, not auto-detected mode
+            assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+
+    def test_case_insensitive_mode_names(self):
+        """Test MCP_DEPLOYMENT_MODE is case-insensitive."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "OAUTH_SINGLE_AUDIENCE",  # Uppercase
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
+
+    def test_whitespace_in_mode_name_stripped(self):
+        """Test whitespace in MCP_DEPLOYMENT_MODE is stripped."""
+        with patch.dict(
+            os.environ,
+            {
+                "NEXTCLOUD_HOST": "http://localhost:8080",
+                "MCP_DEPLOYMENT_MODE": "  oauth_single_audience  ",  # Whitespace
+            },
+            clear=True,
+        ):
+            from nextcloud_mcp_server.config import get_settings
+
+            settings = get_settings()
+            mode = detect_auth_mode(settings)
+
+            assert mode == AuthMode.OAUTH_SINGLE_AUDIENCE
@@ -0,0 +1,308 @@
+"""
+Unit tests for hybrid authentication mode OAuth setup.
+
+Tests the setup_oauth_config_for_multi_user_basic() function that enables
+hybrid authentication where MCP operations use BasicAuth and management
+APIs use OAuth.
+"""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import httpx
+import pytest
+
+from nextcloud_mcp_server.app import setup_oauth_config_for_multi_user_basic
+from nextcloud_mcp_server.config import Settings
+
+pytestmark = pytest.mark.unit
+
+
+@pytest.fixture
+def hybrid_auth_settings():
+    """Create settings for hybrid auth mode testing."""
+    return Settings(
+        nextcloud_host="https://nextcloud.example.com",
+        enable_offline_access=False,  # Start with offline access disabled
+    )
+
+
+@pytest.fixture
+def oidc_discovery_response():
+    """Mock OIDC discovery endpoint response."""
+    return {
+        "issuer": "https://nextcloud.example.com",
+        "authorization_endpoint": "https://nextcloud.example.com/apps/oidc/authorize",
+        "token_endpoint": "https://nextcloud.example.com/apps/oidc/token",
+        "userinfo_endpoint": "https://nextcloud.example.com/apps/oidc/userinfo",
+        "jwks_uri": "https://nextcloud.example.com/apps/oidc/jwks",
+        "introspection_endpoint": "https://nextcloud.example.com/apps/oidc/introspect",
+        "registration_endpoint": "https://nextcloud.example.com/apps/oidc/register",
+        "scopes_supported": ["openid", "profile", "email", "offline_access"],
+        "response_types_supported": ["code"],
+        "grant_types_supported": ["authorization_code", "refresh_token"],
+        "subject_types_supported": ["public"],
+        "id_token_signing_alg_values_supported": ["RS256"],
+    }
+
+
+class TestSetupOAuthConfigForMultiUserBasic:
+    """Test setup_oauth_config_for_multi_user_basic() function."""
+
+    async def test_successful_setup_without_offline_access(
+        self, hybrid_auth_settings, oidc_discovery_response, mocker
+    ):
+        """Test successful OAuth setup without offline access."""
+        # Mock httpx.AsyncClient
+        mock_response = MagicMock()
+        mock_response.json = MagicMock(return_value=oidc_discovery_response)
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(return_value=mock_response)
+        mock_client.__aenter__.return_value = mock_client
+        mock_client.__aexit__.return_value = AsyncMock()
+
+        mocker.patch("httpx.AsyncClient", return_value=mock_client)
+
+        # Call function
+        (
+            verifier,
+            storage,
+            client_id,
+            client_secret,
+        ) = await setup_oauth_config_for_multi_user_basic(
+            settings=hybrid_auth_settings,
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+        )
+
+        # Verify OIDC discovery was called
+        mock_client.get.assert_called_once_with(
+            "https://nextcloud.example.com/.well-known/openid-configuration"
+        )
+
+        # Verify settings were updated
+        assert hybrid_auth_settings.oidc_client_id == "test-client-id"
+        assert hybrid_auth_settings.oidc_client_secret == "test-client-secret"
+        assert hybrid_auth_settings.oidc_issuer == "https://nextcloud.example.com"
+        assert (
+            hybrid_auth_settings.jwks_uri
+            == "https://nextcloud.example.com/apps/oidc/jwks"
+        )
+        assert (
+            hybrid_auth_settings.introspection_uri
+            == "https://nextcloud.example.com/apps/oidc/introspect"
+        )
+        assert (
+            hybrid_auth_settings.userinfo_uri
+            == "https://nextcloud.example.com/apps/oidc/userinfo"
+        )
+
+        # Verify token verifier was created
+        assert verifier is not None
+        from nextcloud_mcp_server.auth.unified_verifier import UnifiedTokenVerifier
+
+        assert isinstance(verifier, UnifiedTokenVerifier)
+
+        # Verify storage is None (offline access disabled)
+        assert storage is None
+
+        # Verify credentials returned
+        assert client_id == "test-client-id"
+        assert client_secret == "test-client-secret"
+
+    async def test_successful_setup_with_offline_access(
+        self, hybrid_auth_settings, oidc_discovery_response, mocker
+    ):
+        """Test successful OAuth setup with offline access enabled."""
+        # Enable offline access
+        hybrid_auth_settings.enable_offline_access = True
+
+        # Generate a valid Fernet key for testing
+        from cryptography.fernet import Fernet
+
+        valid_fernet_key = Fernet.generate_key().decode()
+
+        # Mock TOKEN_ENCRYPTION_KEY environment variable
+        mocker.patch(
+            "os.getenv",
+            side_effect=lambda k, default=None: {
+                "TOKEN_ENCRYPTION_KEY": valid_fernet_key,
+                "NEXTCLOUD_MCP_SERVER_URL": "http://localhost:8000",
+            }.get(k, default),
+        )
+
+        # Mock httpx.AsyncClient
+        mock_response = MagicMock()
+        mock_response.json = MagicMock(return_value=oidc_discovery_response)
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(return_value=mock_response)
+        mock_client.__aenter__.return_value = mock_client
+        mock_client.__aexit__.return_value = AsyncMock()
+
+        mocker.patch("httpx.AsyncClient", return_value=mock_client)
+
+        # Call function
+        (
+            verifier,
+            storage,
+            client_id,
+            client_secret,
+        ) = await setup_oauth_config_for_multi_user_basic(
+            settings=hybrid_auth_settings,
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+        )
+
+        # Verify storage was created
+        assert storage is not None
+        from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+        assert isinstance(storage, RefreshTokenStorage)
+
+    async def test_discovered_urls_used_directly(
+        self, hybrid_auth_settings, oidc_discovery_response, mocker
+    ):
+        """Test that discovered URLs are used directly without rewriting."""
+        # Mock httpx.AsyncClient
+        mock_response = MagicMock()
+        mock_response.json = MagicMock(return_value=oidc_discovery_response)
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(return_value=mock_response)
+        mock_client.__aenter__.return_value = mock_client
+        mock_client.__aexit__.return_value = AsyncMock()
+
+        mocker.patch("httpx.AsyncClient", return_value=mock_client)
+
+        # Call function
+        (
+            verifier,
+            storage,
+            client_id,
+            client_secret,
+        ) = await setup_oauth_config_for_multi_user_basic(
+            settings=hybrid_auth_settings,
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+        )
+
+        # Verify discovered URLs are used directly (not rewritten)
+        assert hybrid_auth_settings.jwks_uri == oidc_discovery_response["jwks_uri"]
+        assert (
+            hybrid_auth_settings.introspection_uri
+            == oidc_discovery_response["introspection_endpoint"]
+        )
+        assert (
+            hybrid_auth_settings.userinfo_uri
+            == oidc_discovery_response["userinfo_endpoint"]
+        )
+
+        # Verify issuer is used directly for JWT validation
+        assert hybrid_auth_settings.oidc_issuer == oidc_discovery_response["issuer"]
+
+    async def test_oidc_discovery_failure_http_error(
+        self, hybrid_auth_settings, mocker
+    ):
+        """Test handling of OIDC discovery HTTP errors."""
+
+        # Create a mock response with a status error
+        mock_response = MagicMock()
+        mock_response.status_code = 404
+        mock_response.raise_for_status.side_effect = httpx.HTTPStatusError(
+            "Not Found",
+            request=MagicMock(),
+            response=MagicMock(status_code=404),
+        )
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(return_value=mock_response)
+        mock_client.__aenter__.return_value = mock_client
+        # Return None to propagate exceptions (not suppress them)
+        mock_client.__aexit__ = AsyncMock(return_value=None)
+
+        mocker.patch("httpx.AsyncClient", return_value=mock_client)
+
+        # Should raise ValueError with helpful message (not UnboundLocalError)
+        with pytest.raises(ValueError, match="OIDC discovery failed"):
+            await setup_oauth_config_for_multi_user_basic(
+                settings=hybrid_auth_settings,
+                client_id="test-client-id",
+                client_secret="test-client-secret",
+            )
+
+    async def test_oidc_discovery_failure_connection_error(
+        self, hybrid_auth_settings, mocker
+    ):
+        """Test handling of OIDC discovery connection errors."""
+        import httpx
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(
+            side_effect=httpx.ConnectError("Connection refused")
+        )
+        mock_client.__aenter__.return_value = mock_client
+        # Return None to propagate exceptions (not suppress them)
+        mock_client.__aexit__ = AsyncMock(return_value=None)
+
+        mocker.patch("httpx.AsyncClient", return_value=mock_client)
+
+        # Should raise ValueError with helpful message
+        with pytest.raises(ValueError, match="Cannot connect to"):
+            await setup_oauth_config_for_multi_user_basic(
+                settings=hybrid_auth_settings,
+                client_id="test-client-id",
+                client_secret="test-client-secret",
+            )
+
+    async def test_missing_nextcloud_host(self):
+        """Test that missing NEXTCLOUD_HOST raises ValueError."""
+        settings = Settings()  # No nextcloud_host set
+
+        with pytest.raises(ValueError, match="NEXTCLOUD_HOST is required"):
+            await setup_oauth_config_for_multi_user_basic(
+                settings=settings,
+                client_id="test-client-id",
+                client_secret="test-client-secret",
+            )
+
+    async def test_custom_discovery_url(
+        self, hybrid_auth_settings, oidc_discovery_response, mocker
+    ):
+        """Test using custom OIDC discovery URL."""
+        # Mock OIDC_DISCOVERY_URL environment variable
+        custom_discovery_url = (
+            "https://custom.idp.example.com/.well-known/openid-configuration"
+        )
+        mocker.patch(
+            "os.getenv",
+            side_effect=lambda k, default=None: {
+                "OIDC_DISCOVERY_URL": custom_discovery_url,
+                "NEXTCLOUD_MCP_SERVER_URL": "http://localhost:8000",
+            }.get(k, default),
+        )
+
+        # Mock httpx.AsyncClient
+        mock_response = MagicMock()
+        mock_response.json = MagicMock(return_value=oidc_discovery_response)
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.get = AsyncMock(return_value=mock_response)
+        mock_client.__aenter__.return_value = mock_client
+        mock_client.__aexit__.return_value = AsyncMock()
+
+        mocker.patch("httpx.AsyncClient", return_value=mock_client)
+
+        # Call function
+        await setup_oauth_config_for_multi_user_basic(
+            settings=hybrid_auth_settings,
+            client_id="test-client-id",
+            client_secret="test-client-secret",
+        )
+
+        # Verify custom discovery URL was used
+        mock_client.get.assert_called_once_with(custom_discovery_url)
@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.4.4"
+version = "0.7.0"
 tag_format = "astrolabe-v$version"
 version_scheme = "semver"
 update_changelog_on_bump = true
@@ -30,7 +30,7 @@ jobs:

      - name: Get version matrix
        id: versions
-        uses: icewind1991/nextcloud-version-matrix@58becf3b4bb6dc6cef677b15e2fd8e7d48c0908f # v1.0.0
+        uses: icewind1991/nextcloud-version-matrix@c2bf575a3516752db5ce2915499d3f694885e2c7 # v1.0.0

  php-lint:
    runs-on: ubuntu-latest
@@ -66,7 +66,7 @@ jobs:

      - name: Create Pull Request
        if: steps.checkout.outcome == 'success'
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
+        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7.0.11
        with:
          token: ${{ secrets.COMMAND_BOT_PAT }}
          commit-message: 'fix(deps): Fix npm audit'
@@ -85,7 +85,7 @@ jobs:
        continue-on-error: true

      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
+        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7.0.11
        with:
          token: ${{ secrets.COMMAND_BOT_PAT }}
          commit-message: 'chore(dev-deps): Bump nextcloud/ocp package'
@@ -25,6 +25,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Requires external MCP server deployment
 - See documentation for setup: https://github.com/cbcoutinho/nextcloud-mcp-server

+## astrolabe-v0.7.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
+- **helm**: add support for multi-user BasicAuth mode
+
+### 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
+- **helm**: set OIDC client env vars when using existingSecret
+- **helm**: trigger chart release workflow on helm chart tags
+- **helm**: address PR #447 reviewer feedback
+- **helm**: include MCP server version bumps in changelog pattern
+
+### Refactor
+
+- **auth**: Decouple BasicAuth and OAuth authentication strategies
+
+## astrolabe-v0.6.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)
+
+## astrolabe-v0.5.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
+
 ## astrolabe-v0.4.4 (2025-12-20)

 ### Fix
@@ -29,7 +29,7 @@ Astrolabe connects to a semantic search service that understands the meaning of

 See [documentation](https://github.com/cbcoutinho/nextcloud-mcp-server) for configuration details.
 	]]></description>
-	<version>0.4.4</version>
+	<version>0.7.0</version>
 	<licence>agpl</licence>
 	<author homepage="https://github.com/cbcoutinho">Chris Coutinho</author>
 	<namespace>Astrolabe</namespace>
--- a/Show More
+++ b/Show More