docs(adr-022): mark Accepted, update env/compose/migration docs for LOGIN_FLOW rename

Follow-up to the LOGIN_FLOW rename. The user-facing surface area —
env.sample, docker-compose.yml mcp-login-flow profile, migration
guide, ADR statuses, and the running.md boot-log examples — all need
to refer to `login_flow` rather than the deprecated
`oauth_single_audience` string.

- docker-compose.yml: add explicit MCP_DEPLOYMENT_MODE=login_flow to
  the mcp-login-flow profile (no longer relying on auto-detection).
- env.sample: update the deployment-mode list and example, dropping
  the removed `oauth_token_exchange` and pointing at ADR-022 for the
  rename rationale.
- docs/ADR-022: flip Status to Accepted with a note that this PR
  implements step 1 (rename + validation gate).
- docs/ADR-021: note that it has been partly superseded by ADR-022
  (the oauth_single_audience naming is no longer accurate); cross-link.
- docs/ADR-025: drop oauth_single_audience/keycloak from the dynaconf
  validator example and the [oauth_single_audience] TOML section.
- docs/configuration-migration-v2.md: bulk-replace oauth_single_audience
  → login_flow throughout (sed -i).
- docs/running.md: re-collapse the per-mode boot-log subsections (added
  during the closed PR #786 workaround) back into a uniform
  "<mode>"-substitution block — now correct after this PR's logging
  cleanup at app.py:1172.

No code changes in this commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docker-compose.yml

@@ -275,7 +275,9 @@ services:
       #- NEXTCLOUD_MCP_SERVER_URL=https://nextcloud-mcp-dev.tail148d5.ts.net
       - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
 
-      # Login Flow v2 (ADR-022)
+      # Login Flow v2 (ADR-022) — explicit mode + the flag that enables the
+      # browser-based app-password acquisition layer
+      - MCP_DEPLOYMENT_MODE=login_flow
       - ENABLE_LOGIN_FLOW=true
 
       # Token storage (required for app password + session persistence).

docs/ADR-021-configuration-consolidation.md

@@ -1,9 +1,9 @@
 # ADR-021: Configuration Consolidation and Simplification
 
-**Status:** Accepted
+**Status:** Accepted — partly superseded by ADR-022 (`oauth_single_audience` renamed to `login_flow`; `oauth_token_exchange` removed)
 **Date:** 2025-12-21
 **Deciders:** Development Team
-**Related:** ADR-020 (Deployment Modes), ADR-002 (Vector Sync), ADR-004 (Progressive Consent)
+**Related:** ADR-020 (Deployment Modes), ADR-002 (Vector Sync), ADR-004 (Progressive Consent), ADR-022 (Deployment Mode Consolidation)
 
 ## Context
 

docs/ADR-022-deployment-mode-consolidation.md

@@ -1,7 +1,7 @@
 # ADR-022: Deployment Mode Consolidation via Login Flow v2
 
-**Status:** Proposed
+**Status:** Accepted (step 1 — `OAUTH_SINGLE_AUDIENCE` → `LOGIN_FLOW` rename + validation gate. Dead-code pruning is a follow-up.)
-**Date:** 2026-02-01
+**Date:** 2026-02-01 (accepted 2026-05-12)
 **Deciders:** Development Team
 **Related:** ADR-020 (Deployment Modes), ADR-021 (Configuration Consolidation), ADR-004 (Progressive Consent), Issue #521
 

docs/ADR-025-dynaconf-configuration-management.md

@@ -108,8 +108,9 @@ nextcloud_verify_ssl = true
 nextcloud_ca_bundle = "@none"
 
 # === Deployment Mode ===
-# Auto-detected if not set. Valid: single_user_basic, multi_user_basic,
+# Auto-detected if not set. Valid: single_user_basic, multi_user_basic, login_flow
-# oauth_single_audience, login_flow, keycloak
+# (`oauth_single_audience` was renamed to `login_flow` in ADR-022; `keycloak`
+# is a planned future mode.)
 # mcp_deployment_mode = ""
 
 # === Authentication Toggles ===
@@ -209,7 +210,7 @@ enable_token_exchange = true
 token_storage_db = "/app/data/tokens.db"
 token_exchange_cache_ttl = 300
 
-[oauth_single_audience]
+[login_flow]
 token_storage_db = "/app/data/tokens.db"
 ```
 
@@ -281,7 +282,6 @@ validators = [
     # Deployment mode validation — catch typos at startup
     Validator("MCP_DEPLOYMENT_MODE", is_in=[
         "single_user_basic", "multi_user_basic", "login_flow",
-        "keycloak", "oauth_single_audience",
     ], when=Validator("MCP_DEPLOYMENT_MODE", must_exist=True)),
 
     # Type and range validation

docs/configuration-migration-v2.md

@@ -106,7 +106,7 @@ NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
 
 # Optional: Explicit mode declaration
-MCP_DEPLOYMENT_MODE=oauth_single_audience
+MCP_DEPLOYMENT_MODE=login_flow
 
 # One variable does it all!
 ENABLE_SEMANTIC_SEARCH=true  # Automatically enables background operations
@@ -131,7 +131,7 @@ NEXTCLOUD_OIDC_CLIENT_SECRET=secret
 **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`
+3. Optionally add `MCP_DEPLOYMENT_MODE=login_flow`
 4. Restart server
 5. Check logs for confirmation: "Automatically enabled background operations for semantic search"
 
@@ -161,7 +161,7 @@ NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=
 
 # Optional: Explicit mode declaration
-MCP_DEPLOYMENT_MODE=oauth_single_audience
+MCP_DEPLOYMENT_MODE=login_flow
 
 # Renamed for clarity
 ENABLE_BACKGROUND_OPERATIONS=true  # Previously ENABLE_OFFLINE_ACCESS
@@ -178,7 +178,7 @@ NEXTCLOUD_OIDC_CLIENT_SECRET=secret
 
 **Migration Steps:**
 1. Replace `ENABLE_OFFLINE_ACCESS=true` with `ENABLE_BACKGROUND_OPERATIONS=true`
-2. Optionally add `MCP_DEPLOYMENT_MODE=oauth_single_audience`
+2. Optionally add `MCP_DEPLOYMENT_MODE=login_flow`
 3. Restart server
 
 ---
@@ -321,7 +321,7 @@ 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
+MCP_DEPLOYMENT_MODE=login_flow
 
 # Explicitly enable background operations for future features
 ENABLE_BACKGROUND_OPERATIONS=true
@@ -352,7 +352,7 @@ 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
+MCP_DEPLOYMENT_MODE=login_flow
 NEXTCLOUD_HOST=https://nextcloud.example.com
 # Clear: This is OAuth mode
 ```
@@ -363,7 +363,7 @@ NEXTCLOUD_HOST=https://nextcloud.example.com
 |-----------|-------------|
 | `single_user_basic` | Single-user with username/password |
 | `multi_user_basic` | Multi-user with BasicAuth pass-through |
-| `oauth_single_audience` | Multi-user OAuth (recommended) |
+| `login_flow` | Multi-user OAuth (recommended) |
 | `oauth_token_exchange` | Multi-user OAuth with token exchange |
 
 ### Mode Detection Priority
@@ -430,7 +430,7 @@ WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENAB
 
 **Symptom:**
 ```
-Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
+Error: [login_flow] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
 ```
 
 **Solution:**
@@ -442,7 +442,7 @@ When semantic search is enabled in multi-user modes, you need:
 ### Issue: Unexpected Mode Detected
 
 **Symptom:**
-Server activates `oauth_single_audience` mode when you expected `multi_user_basic`
+Server activates `login_flow` mode when you expected `multi_user_basic`
 
 **Solution:**
 Add explicit mode declaration:
@@ -483,7 +483,7 @@ docker-compose up mcp
 
 **Expected Log Output (Multi-User OAuth + Semantic Search):**
 ```
-INFO: Using explicit deployment mode: oauth_single_audience
+INFO: Using explicit deployment mode: login_flow
 INFO: Automatically enabled background operations for semantic search in multi-user mode.
 INFO: Vector sync enabled. Starting background scanner...
 ```

docs/running.md

@@ -336,29 +336,19 @@ messages in the container logs:
 **At server boot (all modes):**
 ```
 INFO     ✅ Configuration validated successfully for <mode> mode
+INFO     Configuring MCP server for <mode> mode
 INFO     Health check endpoints enabled: /health/live, /health/ready
 ```
 
-`<mode>` is one of `single_user_basic`, `multi_user_basic`, or
+`<mode>` is one of `single_user_basic`, `multi_user_basic`, or `login_flow`,
-`oauth_single`, matching the `MCP_DEPLOYMENT_MODE` setting.
+matching the `MCP_DEPLOYMENT_MODE` setting.
-
-**Additional BasicAuth-mode messages (at server boot):**
-```
-INFO     Configuring MCP server for <mode> mode
-```
-
-Here `<mode>` is the enum value (`single_user_basic` or `multi_user_basic`).
 
 **Additional OAuth-mode messages (at server boot):**
 ```
-INFO     Configuring MCP server for OAuth mode
 INFO     OAuth client ready: <client-id>...
 INFO     OAuth configuration complete
 ```
 
-Note the OAuth boot line logs the literal string `OAuth mode`, not the enum
-value `oauth_single`.
-
 **Additional single-user BasicAuth messages (per MCP session):**
 
 These fire when the first MCP client connects, not at server boot — if you

env.sample

@@ -3,11 +3,15 @@
 # ============================================
 # 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,
+# Valid values: single_user_basic, multi_user_basic, login_flow
-#               oauth_token_exchange
+#
+# Note: `login_flow` is the renamed successor of the former
+# `oauth_single_audience` mode (see ADR-022). The un-augmented OAuth path
+# required unmerged Nextcloud user_oidc patches and is no longer supported;
+# `login_flow` mode now requires ENABLE_LOGIN_FLOW=true.
 #
 # Recommendation: Set this for clarity and to catch configuration errors early
-#MCP_DEPLOYMENT_MODE=oauth_single_audience
+#MCP_DEPLOYMENT_MODE=login_flow
 
 # ============================================
 # COMMON SETTINGS (Required for all modes)