docs(bot): OAuth connections require migrating the legacy bot registration

[wkatir]

Description

A setup guide (docs/bot-oauth-setup.md) for enabling Bot Framework OAuth connections on a locally debugged bot - required by any feature where the bot calls Microsoft Graph on behalf of the chatting user.

Teams Toolkit's local-debug provisioning (botFramework/create in teamsapp.local.yml) creates a legacy registration in the old Bot Framework portal (dev.botframework.com). That portal removed its OAuth Connection Settings section - connections can only be configured on an Azure Bot resource - so a locally debugged bot cannot use the token service until its registration is migrated.

Hit this while wiring up the calendar suggestions (#170); documenting it saves the next person the discovery time.

Type of Change

• Bug fix
• New feature
• Enhancement
• Breaking change
• Documentation update

Related Issues

Related to #168 / #170 (calendar suggestions need this setup; the future e-mail phase will too). No issue is closed by this PR.

Changes Made

The guide covers:

• Why the legacy registration cannot hold OAuth connections.
• Migrating to an Azure Bot (one-way but safe: keeps App ID, endpoint and the Teams channel; F0 tier is free).
• Keeping local debug working afterwards: botFramework/create targets the now-gone legacy registration, so it must be replaced with an az bot update --endpoint script step.
• Creating the connection with az bot authsetting create, including the tokenExchangeUrl gotcha that silently breaks Teams SSO when it does not match the SSO app's Application ID URI.
• How to verify (silent SSO on connect calendar - a sign-in card appearing means the connection settings are wrong).

Docs only - no code changes. teamsapp.local.yml is intentionally untouched: the replacement step hardcodes each developer's own resource group, so it stays a documented local edit.

Screenshots (if applicable)

Not applicable - documentation only.

Test plan for QA

Follow the guide top to bottom on a fresh local-debug bot: migrate, patch the yml, create the connection, then connect calendar connects silently and the agent answers questions about recent meetings.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have tested my changes locally
• My changes generate no new warnings
• I have added/updated documentation as needed

🤖 Generated with Claude Code