diff --git a/README.md b/README.md
index 35402309..c0625999 100644
--- a/README.md
+++ b/README.md
@@ -73,7 +73,7 @@ For Kubernetes, see [cbcoutinho/helm-charts](https://github.com/cbcoutinho/helm-
 - **Semantic Search (Experimental)** - Optional vector-powered search for Notes, Files, News items, and Deck cards (requires Qdrant + Ollama)
 - **Document Processing** - OCR and text extraction from PDFs, DOCX, images with progress notifications
 - **Flexible Deployment** - Docker, Kubernetes ([Helm chart](https://github.com/cbcoutinho/helm-charts)), VM, or local installation
-- **Production-Ready Auth** - Basic Auth with app passwords; multi-user via Login Flow v2 (OAuth-to-MCP supported, with app-password conversion to Nextcloud)
+- **Production-Ready Auth** - Basic Auth with app passwords; multi-user via Login Flow v2 — MCP clients authenticate via OAuth, the server handles Nextcloud app passwords transparently
 - **Multiple Transports** - streamable-http (default) and stdio
 
 ## Supported Apps
diff --git a/docs/auth-flows.md b/docs/auth-flows.md
index 46d357f6..4ebf4857 100644
--- a/docs/auth-flows.md
+++ b/docs/auth-flows.md
@@ -109,7 +109,7 @@ Astrolabe                     MCP Server                   Nextcloud
 #### Astrolabe → MCP Server
 
 ```
-Astrolabe                     MCP Server                   Nextcloud OIDC
+Astrolabe                     MCP Server                   OIDC Provider
     │                             │                            │
     │── OAuth Flow ──────────────▶│◀── Token from IdP ────────▶│
     │   (user initiates)          │                            │
diff --git a/docs/login-flow-v2.md b/docs/login-flow-v2.md
index 468d5321..73c91ab4 100644
--- a/docs/login-flow-v2.md
+++ b/docs/login-flow-v2.md
@@ -104,6 +104,8 @@ mcp-login-flow:
     - NEXTCLOUD_MCP_SERVER_URL=http://localhost:8004
     - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
     - ENABLE_LOGIN_FLOW=true
+    # Dev-only inline value. In production, mount via Docker secret and read
+    # from a *_FILE env var or a secrets-management init step.
     - TOKEN_ENCRYPTION_KEY=<your-fernet-key>
     - TOKEN_STORAGE_DB=/app/data/tokens.db
   volumes:
@@ -111,6 +113,8 @@ mcp-login-flow:
     - login-flow-oauth-storage:/app/.oauth
 ```
 
+> **Production note:** `TOKEN_ENCRYPTION_KEY` is a credential — losing it makes every stored app password unrecoverable. Inline-environment values are fine for local development but should be passed via Docker secrets (or your platform's equivalent) in production. See [Configuration → Best Practices for Docker](configuration.md#for-docker).
+
 The `--oauth` flag enables the OAuth/OIDC identity layer that Login Flow v2 builds on (user identity via OAuth session, Nextcloud access via app passwords).
 
 ## Per-User Provisioning Flow
@@ -226,7 +230,7 @@ Implementation: [`nextcloud_mcp_server/auth/scope_authorization.py`](../nextclou
 
 ## OAuth Endpoints
 
-When `--oauth` is enabled, the MCP server exposes OAuth 2.1 endpoints. **These endpoints front the configured IdP** — discovery metadata, token issuance, and JWKS still come from whichever provider is selected via `OIDC_DISCOVERY_URL` (Nextcloud OIDC by default, or Keycloak / Cognito / etc.); the MCP server is not a standalone OAuth issuer.
+When `--oauth` is enabled, the MCP server exposes OAuth 2.1 endpoints. **These endpoints front the configured IdP**: discovery metadata is sourced from the IdP, and tokens served via the MCP server's `/token` endpoint are signed by the IdP's key and validated against its JWKS — the MCP server has no signing keys of its own. The IdP is selected by `OIDC_DISCOVERY_URL` (Nextcloud OIDC by default, or Keycloak / Cognito / etc.).
 
 | Endpoint | RFC | Purpose |
 |----------|-----|---------|