docs: address remaining Login Flow v2 review feedback

Round-2 cleanup of PR #743 review comments not covered by d153e96:

- configuration.md: fix broken `#multi-user-oauth-modes` anchor; replace
  with the two real anchors (Multi-User BasicAuth, Login Flow v2). Rewrite
  the stale "always use OAuth2/OIDC with pre-configured clients" Best
  Practices section to reflect the post-pivot mode matrix, and update the
  Docker volume example to mount the encrypted app-password store
  (`TOKEN_STORAGE_DB`) rather than obsolete `.oauth` client storage.
- semantic-search-architecture.md: rename remaining body references from
  the deprecated `VECTOR_SYNC_ENABLED` to `ENABLE_SEMANTIC_SEARCH` so the
  doc matches configuration.md / troubleshooting.md.
- running.md: relabel "OAuth Mode (Recommended)" as
  "Login Flow v2 / OAuth issuer mode (--oauth)", drop the misleading
  "(Legacy)" suffix from BasicAuth, drop the
  `NEXTCLOUD_OIDC_CLIENT_ID/SECRET` example (tied to the retired
  direct-OAuth-to-Nextcloud flow), and add a note explaining what
  `--oauth` actually enables post-pivot.
- keycloak-multi-client-validation.md, oauth-impersonation-findings.md:
  add a deprecation banner pointing at ADR-022 / Login Flow v2. Files
  retained because ADR-002 and CLAUDE.md still cite them.
- auth-flows.md: clarify under the Astrolabe → MCP diagram that the
  Nextcloud-OIDC JWKS path applies to Multi-User BasicAuth; under
  Login Flow v2 the MCP server validates tokens against its own JWKS.
- login-flow-v2.md: clarify the sticky-session note — affinity must key
  on the OAuth bearer token (or user-bound cookie), not source IP, since
  MCP clients may not maintain stable IPs across the provisioning flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2026-04-30 01:57:16 +02:00
co-authored by Claude Opus 4.7
parent 074d20998c
commit 35c115ead6
7 changed files with 47 additions and 32 deletions
+10 -10
View File
@@ -86,7 +86,7 @@ graph TB
## How It Works: Background Synchronization
Background synchronization runs automatically when `VECTOR_SYNC_ENABLED=true`, discovering changes and indexing documents without user intervention.
Background synchronization runs automatically when `ENABLE_SEMANTIC_SEARCH=true`, discovering changes and indexing documents without user intervention.
```mermaid
sequenceDiagram
@@ -478,7 +478,7 @@ except Exception as e:
**BasicAuth:**
- Set `NEXTCLOUD_USERNAME` and `NEXTCLOUD_PASSWORD`
- Background sync works immediately when `VECTOR_SYNC_ENABLED=true`
- Background sync works immediately when `ENABLE_SEMANTIC_SEARCH=true`
- Credentials stored in `.env` file (secure server access required)
**OAuth:**
@@ -497,7 +497,7 @@ except Exception as e:
**In-Memory Mode:**
```bash
VECTOR_SYNC_ENABLED=true
ENABLE_SEMANTIC_SEARCH=true
# QDRANT_LOCATION not set → defaults to :memory:
```
- Fastest startup
@@ -506,7 +506,7 @@ VECTOR_SYNC_ENABLED=true
**Persistent Local Mode:**
```bash
VECTOR_SYNC_ENABLED=true
ENABLE_SEMANTIC_SEARCH=true
QDRANT_LOCATION=/var/lib/qdrant
```
- Vectors survive restarts
@@ -515,7 +515,7 @@ QDRANT_LOCATION=/var/lib/qdrant
**Network Mode (Recommended for Production):**
```bash
VECTOR_SYNC_ENABLED=true
ENABLE_SEMANTIC_SEARCH=true
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=secret # optional
```
@@ -563,12 +563,12 @@ OLLAMA_EMBEDDING_MODEL=nomic-embed-text # 768-dimensional vectors
**Enable Semantic Search:**
```bash
VECTOR_SYNC_ENABLED=true # Default: false (opt-in)
ENABLE_SEMANTIC_SEARCH=true # Default: false (opt-in)
```
**Qdrant Vector Database:**
```bash
# In-memory mode (default if VECTOR_SYNC_ENABLED=true)
# In-memory mode (default if ENABLE_SEMANTIC_SEARCH=true)
# QDRANT_LOCATION not set → uses :memory:
# Persistent local mode
@@ -617,7 +617,7 @@ VECTOR_SYNC_INTERVAL=3600 # Scan interval in seconds (default: 1 hour)
## Operational Behavior
### What Happens When VECTOR_SYNC_ENABLED=true
### What Happens When ENABLE_SEMANTIC_SEARCH=true
**Immediate (Server Startup):**
1. MCP server connects to Qdrant (creates collection if needed)
@@ -752,7 +752,7 @@ For detailed observability setup, see [docs/observability.md](observability.md).
**Diagnosis Flow:**
1. Check sync status: `nc_get_vector_sync_status`
- `sync_enabled: false` → Enable with `VECTOR_SYNC_ENABLED=true`
- `sync_enabled: false` → Enable with `ENABLE_SEMANTIC_SEARCH=true`
- `status: error` → Check scanner logs for failures
2. Check queue size:
- `pending_documents > 0` → Processing in progress, wait
@@ -765,7 +765,7 @@ For detailed observability setup, see [docs/observability.md](observability.md).
- Model not found → Pull model: `ollama pull nomic-embed-text`
**Common Causes:**
- Sync disabled (default): Enable `VECTOR_SYNC_ENABLED=true`
- Sync disabled (default): Enable `ENABLE_SEMANTIC_SEARCH=true`
- Ollama not running: Start Ollama service
- Qdrant not accessible: Check network/URL
- First scan in progress: Wait up to 1 hour + processing time