docs(auth): operator guide for oauth multi-tenant (PR-5)

[IgorShevchik]

Summary

The final step of the OAuth rollout (OAUTH-DESIGN.md §10, PR-5). The code path landed across #209 → #210 → #213 → #216 → #218; this PR makes it operator-discoverable and finalizes the env surface. No code changes — docs + .env.example only.

The headline deliverable is the migration warning: when NUXT_BITRIX24_OAUTH_ENABLED=true, NUXT_MCP_AUTH_TOKEN is bypassed on /mcp and the endpoint accepts only per-user OAuth Bearers. An operator who flips the flag without migrating clients first will 401 every connected client. §10 explicitly required this warning to land in PR-5.

What's in the diff

File	Change
.env.example	OAuth block rewritten from staging language (“staged across PR-2a..PR-2c”, “Enable only AFTER PR-2c merges”) to its final form (landed, end-to-end live behind the flag). Added the explicit ⚠ NUXT_MCP_AUTH_TOKEN is bypassed migration warning; finalized the persistent-volume data-loss note (was “PR-5 will warn explicitly” — this is PR-5).
docs/DEPLOYMENT.md	Six OAuth env vars added to the environment table; NUXT_MCP_AUTH_TOKEN flagged ‡ BYPASSED under OAuth; new “OAuth 2.0 multi-tenant (opt-in)” section with the migration warning, the webhook→OAuth upgrade runbook, the single-instance caveat, and the /api/oauth/_health observability note.
README.md	Service-user note softened (OAuth now available, opt-in, off by default); per-user OAuth surfaced in the “Choose your path” table; new “Multi-tenant OAuth 2.0” subsection under Connecting Claude.
skills/run-manual-qa/references/issue-scaffold.md	OAuth intro wording aligned with the finalized .env.example (Manual-QA scaffold-sync mirror — required because .env.example changed).

Migration warning (the load-bearing bit)

When NUXT_BITRIX24_OAUTH_ENABLED=true, NUXT_MCP_AUTH_TOKEN is bypassed on /mcp. The endpoint accepts only a per-user OAuth Bearer minted via /api/oauth/install → /api/oauth/callback. Any client still presenting the old shared token gets a 401 with WWW-Authenticate: Bearer error="invalid_token", errorCode="BEARER-UNKNOWN". Migrate every client to its own Bearer before flipping the flag. Rollback (=false + restart) is non-destructive.

This warning now lives in all three operator surfaces: .env.example, docs/DEPLOYMENT.md, and README.md.

Test plan

• No code touched — typecheck / unit suite unaffected.
• .env.example changed → issue-scaffold.md updated in the same PR (Manual-QA scaffold-sync gate).
• Internal anchors verified (#oauth-20-multi-tenant-opt-in, #multi-tenant-oauth-20--per-user-identity-opt-in).
• Volume name (bx24_data:/data) verified against docker-compose.yml.
• Reviewer: confirm the upgrade runbook matches the actual route names (/api/oauth/install, /api/oauth/callback, /api/oauth/_health) and env-var spellings.

Refs

• OAUTH-DESIGN.md §10 → PR-5 (operator docs), the last rollout step.
• Builds on the merged code path: feat(auth): wire oauth scaffolding — ALS, tenant dispatcher, env (PR-2a) #209, feat(security): oauth token store — sqlite-backed CRUD + audit-first invariant (PR-2b) #210, refactor(auth): swap tool catalogue to useBitrix24Tenant + §11 observability contract (PR-2d) #213, feat(auth): oauth install/callback handshake + b24oauth factory (PR-2c) #216, feat(auth): bearer middleware - /mcp accepts oauth bearers (closes #217) #218 (PR-2c-bearer: wire OAuth Bearer middleware into /mcp (the last connection) #217).

Changelog framing (no BREAKING CHANGE)

• Docs → Auth: operator guide + upgrade runbook for the opt-in OAuth multi-tenant flow; explicit NUXT_MCP_AUTH_TOKEN-bypass migration warning across README / DEPLOYMENT / .env.example.

---

Generated by Claude Code