teams_rb 2.0.1

data/docs/essentials/api-client.md

@@ -0,0 +1,62 @@
+# The API client
+
+`teams.api` (also `ctx.api`) is the low-level Bot Framework client, structured like the other SDKs' API hub. Higher-level helpers (`ctx.reply`, `teams.post`, `ctx.sign_in`) route through it; use it directly when you need the raw surface.
+
+## Conversations
+
+```ruby
+api.conversations.create(members:, tenant_id:, activity: nil, channel_data: nil)  # => ConversationResource
+api.conversations.create_activity(conversation_id, activity)
+api.conversations.reply_to_activity(conversation_id, activity_id, activity)
+api.conversations.update_activity(conversation_id, activity_id, activity)
+api.conversations.delete_activity(conversation_id, activity_id)
+
+# targeted (single-recipient) variants
+api.conversations.create_targeted_activity(conversation_id, activity)
+api.conversations.update_targeted_activity(conversation_id, activity_id, activity)
+api.conversations.delete_targeted_activity(conversation_id, activity_id)
+
+# members — typed Teams::Api::Account results, aadObjectId normalized
+api.conversations.get_members(conversation_id)
+api.conversations.get_member_by_id(conversation_id, member_id)
+api.conversations.get_paged_members(conversation_id, page_size: 200, continuation_token: nil)  # => PagedMembersResult
+api.conversations.get_activity_members(conversation_id, activity_id)
+
+# reactions
+api.conversations.add_reaction(conversation_id, activity_id, "like")
+api.conversations.delete_reaction(conversation_id, activity_id, "like")
+```
+
+For large rosters use `get_paged_members` and feed `continuation_token` back until it returns `nil`.
+
+## Teams and meetings
+
+```ruby
+api.teams.get_by_id(team_id)                       # => TeamDetails
+api.teams.get_conversations(team_id)               # => [ChannelInfo] — the team's channels
+
+api.meetings.get_by_id(meeting_id)                 # => MeetingInfo
+api.meetings.get_participant(meeting_id, aad_object_id, tenant_id)  # => MeetingParticipant
+api.meetings.send_notification(meeting_id, { value: { recipients: [aad_object_id], surfaces: surfaces } })
+```
+
+`send_notification` returns `nil` when every recipient succeeded (202) and a `MeetingNotificationResponse` with per-recipient failures on partial success (207).
+
+## Users and bot sign-in
+
+The token-service clients behind [user authentication](../in-depth-guides/user-authentication.md):
+
+```ruby
+api.users.get_token(user_id:, connection_name:, channel_id: nil, code: nil)     # => TokenResponse
+api.users.get_token_status(user_id:, channel_id:)                              # => [TokenStatus]
+api.users.sign_out(user_id:, connection_name:, channel_id:)
+api.users.exchange_token(user_id:, connection_name:, channel_id:, exchange_request:)
+api.users.get_aad_tokens(user_id:, connection_name:, resource_urls:, channel_id:)
+
+api.bots.sign_in.get_url(state:)        # => String
+api.bots.sign_in.get_resource(state:)   # => SignInUrlResponse
+```
+
+## Errors
+
+Failed requests raise `Teams::HttpError` with `status`, `headers`, `body` (parsed JSON when possible, raw string otherwise), and the request. Streaming sends additionally classify their 403s into typed stream errors ([Streaming](../in-depth-guides/streaming.md)).

data/docs/essentials/app-authentication.md

@@ -0,0 +1,27 @@
+# App authentication
+
+How the app proves itself to Teams, and how Teams proves itself to the app. All of it matches the TypeScript, Python, and .NET SDKs.
+
+## Inbound validation
+
+Every `POST /api/messages` request must carry a Bot Framework JWT. The app validates:
+
+- **Signature** against Microsoft's published signing keys (RS256, JWKS fetched and cached)
+- **Issuer** — the Bot Framework issuer, or your tenant's Entra issuers (v1 and v2 forms) when `TENANT_ID` is configured
+- **Audience** — your app id, in any of the three accepted forms: the bare id, `api://{id}`, `api://botid-{id}`
+- **Expiry / not-before**
+- **`serviceurl` claim** — must match the activity's service URL, preventing spoofed routing
+
+Rejected requests get a 401 with a warn log line. Requests are rejected wholesale when no credentials are configured (with a loud startup warning) unless `skip_auth: true` is set explicitly — which is for local development only.
+
+## Outbound bot tokens
+
+Replies and proactive sends authenticate with an app-only token from the Entra client-credentials flow, acquired and cached automatically (single-flight refresh with expiry skew — the other SDKs get the equivalent from MSAL). Nothing to configure beyond the three credentials.
+
+## The trust model in one paragraph
+
+Teams never talks to your bot directly — the Bot Framework service does, signing every request with Microsoft-issued tokens audienced to *your* app id. Your bot talks back through the service URL from the validated activity, authenticating with *your* app's token. User identity inside activities (`ctx.activity.from`) is asserted by Teams and safe to trust once the JWT validates; user identity for *external* calls (Graph, your own API) comes from [user authentication](../in-depth-guides/user-authentication.md) instead.
+
+## Sovereign clouds
+
+Pass a `cloud:` environment to route logins, token services, and Graph to sovereign endpoints. The public cloud is the default.

data/docs/essentials/app-basics.md

@@ -0,0 +1,50 @@
+# App basics
+
+## Construction
+
+`Teams::App.new` reads configuration from the environment by default; every value can be passed explicitly:
+
+| Env var | Keyword | Required | Purpose |
+|---|---|---|---|
+| `CLIENT_ID` | `client_id:` | production | Bot's Microsoft App ID — bot tokens and inbound JWT audiences |
+| `CLIENT_SECRET` | `client_secret:` | production | Client secret for the client-credentials flow |
+| `TENANT_ID` | `tenant_id:` | single-tenant | Entra tenant for bot tokens and tenant-issuer validation |
+| `SERVICE_URL` | `service_url:` | no | Default Bot Framework URL for proactive sends (inbound requests always use the activity's own service URL) |
+| — | `skip_auth:` | no | Disables inbound validation — local development only |
+| — | `messaging_endpoint:` | no | Inbound path, default `/api/messages` |
+| — | `default_connection_name:` | no | OAuth connection name for user sign-in, default `"graph"` |
+| — | `logger:`, `storage:`, `cloud:` | no | Logger (stdout default), state store (in-memory default), cloud environment for sovereign clouds |
+
+Without credentials the app logs a startup warning and rejects every inbound request unless `skip_auth: true` was set explicitly — the same behavior as the TypeScript, Python, and .NET SDKs.
+
+## One app instance
+
+Construct the app once at boot and share it; it is safe under multi-threaded servers (Puma etc.) — the token cache, storage, and JWKS caches are lock-protected, and per-request state lives on the context.
+
+```ruby
+# config/initializers/teams_bot.rb (Rails) or config.ru (Rack)
+TEAMS_BOT = Teams::App.new
+
+TEAMS_BOT.on_message do |ctx|
+  ctx.reply "hello"
+end
+```
+
+## Serving
+
+`to_rack` produces the Rack app:
+
+```ruby
+# Rack
+run TEAMS_BOT.to_rack
+
+# Rails — route the endpoint path; this preserves the request path,
+# which the endpoint check relies on
+post "/api/messages" => TEAMS_BOT.to_rack
+```
+
+Handlers run inside the web request. Keep them fast; move slow work (LLM calls, long queries) to a job and deliver results later via [proactive messaging](proactive-messaging.md).
+
+## Storage
+
+`ctx.storage` (and `app.storage`) is a simple key-value store with `get`/`set`/`delete`. The default `Teams::Storage::MemoryStore` is thread-safe but process-local — substitute anything answering the same three methods (backed by Redis, Active Record, …) via `storage:`.

data/docs/essentials/graph.md

@@ -0,0 +1,41 @@
+# Microsoft Graph
+
+A thin Graph request client, following the TypeScript SDK's core Graph client. The raw request surface is the API (like TypeScript's `client.http` escape hatch); there are no generated endpoint wrappers, and Ruby has no official Graph SDK to delegate to.
+
+## Two identities
+
+```ruby
+teams.graph          # the app's own identity (app-only tokens) — also ctx.app_graph
+ctx.user_graph       # the signed-in user's identity
+```
+
+- **App identity** uses the client-credentials flow with the Graph scope. Grant the app **application permissions** in Entra for whatever it reads/writes.
+- **User identity** uses the token from [user sign-in](../in-depth-guides/user-authentication.md) and raises `Teams::Error` when the user hasn't signed in. The token carries the OAuth connection's **delegated** scopes.
+
+## Requests
+
+`get` / `post` / `patch` / `put` / `delete`, paths relative to `/v1.0`, parsed-hash returns:
+
+```ruby
+me = ctx.user_graph.get("/me")
+ctx.reply "You are #{me["displayName"]} (#{me["userPrincipalName"]})"
+
+teams.graph.get("/users", params: { "$top" => 5, "$select" => "displayName" })
+teams.graph.post("/users/#{user_id}/sendMail", json: { message: { subject: "Hi" } })
+```
+
+## Errors
+
+Failures raise `Teams::GraphError` with `status`, the Graph error `code` (e.g. `Authorization_RequestDenied`), and the full response `body`:
+
+```ruby
+begin
+  teams.graph.get("/users")
+rescue Teams::GraphError => e
+  ctx.log.warn("Graph denied: #{e.code}") if e.status == 403
+end
+```
+
+## Sovereign clouds
+
+The Graph host derives from the configured cloud's graph scope automatically; `Teams::Graph::Client.new(token:, base_url_root: "https://graph.microsoft.us")` overrides it for hand-built clients.

data/docs/essentials/on-activity.md

@@ -0,0 +1,72 @@
+# Listening to activities
+
+Handlers register against named routes, matching the Python SDK's handler names.
+
+## Messages
+
+```ruby
+teams.on_message do |ctx|                 # every message
+  ctx.reply "you said: #{ctx.activity.text}"
+end
+
+teams.on_message(/^help$/i) do |ctx|      # pattern-filtered (Regexp or exact String)
+  ctx.reply "try: search, create, login"
+end
+```
+
+Message edits and restores route separately:
+
+```ruby
+teams.on_message_update { |ctx| }          # any messageUpdate activity
+teams.on_edit_message { |ctx| }            # user edited a message
+teams.on_undelete_message { |ctx| }        # user restored a deleted message
+```
+
+## Invokes
+
+Each invoke family has named routes — their handler return values become the invoke's HTTP response body:
+
+- Dialogs: `on_dialog_open(dialog_id = nil)`, `on_dialog_submit(action = nil)` — [guide](../in-depth-guides/dialogs.md)
+- Message extensions: `on_message_ext_query`, `on_message_ext_submit`, `on_message_ext_open`, `on_message_ext_query_link`, and five more — [guide](../in-depth-guides/message-extensions.md)
+- Sign-in: `on_signin_token_exchange`, `on_signin_verify_state`, `on_signin_failure` (defaults provided — [guide](../in-depth-guides/user-authentication.md))
+- Feedback: `on_message_submit_feedback` (thumbs up/down from `add_feedback` — [guide](../in-depth-guides/feedback.md)), `on_message_submit` for any `message/submitAction`
+- `on_suggested_action_submit` for suggested-action submissions
+
+## Meeting events
+
+```ruby
+teams.on_meeting_start { |ctx| ctx.post "Meeting #{ctx.activity.value.title} started" }
+teams.on_meeting_end   { |ctx| }
+```
+
+See [Meeting events](../in-depth-guides/meeting-events.md) for the payload details.
+
+## Middleware
+
+`use` registers a handler that sees every activity; calling the second parameter continues the chain. Any handler that declares two parameters participates in chaining:
+
+```ruby
+teams.use do |ctx, nxt|
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  nxt.call
+ensure
+  ctx.log.info("#{ctx.activity.type} handled in #{(Process.clock_gettime(Process::CLOCK_MONOTONIC) - started).round(3)}s")
+end
+```
+
+Handlers run in registration order among those whose route matches the activity; without `nxt.call`, the chain stops.
+
+## The escape hatch
+
+`teams.on(type)` matches raw activity types (`"message"`, `"invoke"`, `"messageReaction"`, `"conversationUpdate"`, …) for anything without a named route. Prefer the named routes when one exists.
+
+```ruby
+teams.on("messageReaction") do |ctx|
+  reaction = ctx.activity.raw["reactionsAdded"]&.first
+  ctx.post "thanks for the #{reaction["type"]}!" if reaction
+end
+```
+
+## Error semantics
+
+A handler that raises produces a 500 response, and Bot Framework then **redelivers the activity** (same `ctx.activity.id`) — this is SDK-family behavior. Deduplicate side effects by activity id when that matters.

data/docs/essentials/on-event.md

@@ -0,0 +1,29 @@
+# Listening to events
+
+Beyond activity routes, the app emits two application-level events, registered with named methods (the Ruby counterpart of the TypeScript/Python event emitters).
+
+## Sign-in
+
+Fires whenever a user sign-in completes through the default OAuth handlers — both the silent token-exchange path and the interactive card path:
+
+```ruby
+teams.on_sign_in do |ctx, token_response|
+  ctx.post "Welcome! You're signed in."
+  # token_response.token is the user's access token for the
+  # OAuth connection's scopes; ctx is the invoke's activity context
+end
+```
+
+See [User authentication](../in-depth-guides/user-authentication.md) for the full flow.
+
+## Errors
+
+Fires when a default OAuth handler hits an unexpected failure, or when the Teams client reports a sign-in failure:
+
+```ruby
+teams.on_error do |error, activity|
+  Honeybadger.notify(error, context: { activity_id: activity&.id })
+end
+```
+
+Handler errors during normal activity processing are not routed here — they surface as 500 responses (and Bot Framework redelivery); log-based monitoring catches those via the app's error log line.

data/docs/essentials/proactive-messaging.md

@@ -0,0 +1,44 @@
+# Proactive messaging
+
+Sending outside an inbound request — from a job, a webhook, your product's backend.
+
+## Conversation references
+
+Inside a handler, `ctx.ref` is a `Teams::Api::ConversationReference` for the current conversation. Persist it, restore it later:
+
+```ruby
+# during a handler
+ConversationRecord.create!(user: current_user, ref: ctx.ref.to_h)
+
+# later, from a job
+ref = Teams::Api::ConversationReference.from_h(record.ref)
+teams.post(ref.conversation_id, "Your report is ready", service_url: ref.service_url)
+```
+
+The proactive surface on the app mirrors the SDK family:
+
+```ruby
+teams.post(conversation_id, activity)                 # send
+teams.reply(conversation_id, activity_id, activity)   # threaded reply
+teams.update(conversation_id, activity_id, activity)  # edit
+```
+
+`teams.reply` threads through the conversation id (`;messageid=...`), like TypeScript and Python.
+
+## Messaging a user without a stored conversation
+
+Create (or re-fetch) the 1:1 conversation — Teams returns the existing conversation when one exists for the same members:
+
+```ruby
+conversation = teams.api.conversations.create(
+  members: [{ id: user_teams_id }],   # the user's Teams id ("29:...")
+  tenant_id: tenant_id
+)
+teams.post(conversation.id, "Hello from your backend")
+```
+
+This is the standard SaaS pattern: notify any user who has the app installed, no prior chat required.
+
+## Service URLs
+
+Proactive sends default to the app's configured `SERVICE_URL`; pass `service_url:` from a stored reference to target the user's regional endpoint (references captured from real activities carry it).

data/docs/essentials/sending-messages.md

@@ -0,0 +1,76 @@
+# Sending messages
+
+## The four verbs
+
+```ruby
+ctx.post "a plain message in the conversation"
+ctx.reply "a threaded reply, quoting the inbound message"
+ctx.quote "message-id", "a reply quoting a specific message"
+ctx.update "activity-id", "replaces a previous bot message"
+```
+
+`post` is Ruby's spelling of the SDKs' `send` (Ruby reserves `Object#send`), with identical semantics — including: an activity that already carries an `id` is **updated** instead of created. `ctx.update` is sugar over exactly that. `reply` adds the Teams quoted-reply entity and placeholder, matching the other SDKs.
+
+All sends accept a String, a `Teams::Api::MessageActivity`, an Adaptive Card, or a raw activity Hash (symbol or string keys — they're normalized).
+
+## SentActivity
+
+Every send returns a `Teams::Api::SentActivity` — the outbound activity merged with the server's response. Keep its `id` to edit later:
+
+```ruby
+sent = ctx.post "Working on it..."
+# ...later...
+ctx.update sent.id, "Done!"
+```
+
+> **Updates replace the activity entirely.** Metadata like the AI-generated label, sensitivity labels, citations, and mentions must be re-attached on every update or they disappear.
+
+## Message activities
+
+`Teams::Api::MessageActivity` is the builder for anything beyond plain text:
+
+```ruby
+ctx.post Teams::Api::MessageActivity.new("**markdown**", text_format: "markdown")
+# text_format: plain | markdown | xml | extendedmarkdown
+
+ctx.post Teams::Api::MessageActivity.new("Quarterly numbers")
+  .add_ai_generated                                          # "AI generated" badge
+  .add_sensitivity_label("Confidential", description: "Internal only")
+  .add_feedback                                              # thumbs up/down feedback buttons
+```
+
+Mentions:
+
+```ruby
+ctx.post Teams::Api::MessageActivity.new("ping ").add_mention(ctx.activity.from.to_h)
+
+if ctx.activity.recipient_mentioned?
+  ctx.reply "you said: #{ctx.activity.strip_mentions_text}"
+end
+```
+
+Citations (for AI answers) attach numbered references — `[1]` in the text links to the citation:
+
+```ruby
+message = Teams::Api::MessageActivity.new("Revenue grew 40% [1].").add_ai_generated
+message.add_citation(1, { "name" => "Q3 Report", "url" => "https://example.com/q3" })
+ctx.post message
+```
+
+> A citation's inline `text` content must be a **stringified Adaptive Card** — Teams rejects the whole message with a 400 otherwise.
+
+## Typing
+
+```ruby
+ctx.typing               # animated ellipsis in the chat
+```
+
+`ctx.typing(text)` exists for wire parity, but the Teams client doesn't render text on a plain typing activity — for a visible status line use `ctx.stream.update("Thinking...")` ([Streaming](../in-depth-guides/streaming.md)).
+
+## Targeted messages
+
+When the inbound message targets the bot (`recipient.isTargeted`), `ctx.post` and `ctx.reply` automatically answer as targeted messages visible only to that user, matching TypeScript/Python — including the `targetedMessageInfo` entity and the targeted API routes. Targeted messages aren't supported in 1:1 chats (the SDK raises).
+
+## Delivery semantics
+
+Bot Framework delivers **at least once**: a slow or failing bot sees the same activity again with the same `ctx.activity.id`. The SDK doesn't deduplicate (none of the SDKs do) — if a side effect must not repeat, guard it by activity id.

data/docs/essentials/sovereign-cloud.md

@@ -0,0 +1,26 @@
+# Sovereign clouds
+
+Government and sovereign cloud tenants use different login, Bot Framework, and Graph endpoints. The app routes everything from a single `cloud:` configuration:
+
+```ruby
+gcch = Teams::CloudEnvironment.new(
+  login_endpoint: "https://login.microsoftonline.us",
+  login_tenant: "botframework.com",
+  bot_scope: "https://api.botframework.us/.default",
+  token_service_url: "https://tokengcch.botframework.azure.us",
+  open_id_metadata_url: "https://login.botframework.azure.us/v1/.well-known/openidconfiguration",
+  token_issuer: "https://api.botframework.us",
+  graph_scope: "https://graph.microsoft.us/.default"
+)
+
+teams = Teams::App.new(cloud: gcch)
+```
+
+Everything derives from the cloud environment automatically:
+
+- **Bot tokens** — requested from the cloud's login endpoint with its bot scope
+- **Inbound validation** — issuer and signing keys from the cloud's metadata
+- **User tokens / sign-in** — the cloud's token service
+- **Graph** — the host is derived from the cloud's graph scope (`https://graph.microsoft.us` above)
+
+The public cloud is the default; nothing to configure outside sovereign deployments. Endpoint values for the specific sovereign clouds are in [Microsoft's sovereign cloud documentation](https://learn.microsoft.com/azure/bot-service/how-to-deploy-gov-cloud-high).

data/docs/getting-started/README.md

@@ -0,0 +1,7 @@
+# Getting started
+
+Everything to go from zero to a bot running inside Teams:
+
+1. [Quickstart](quickstart.md) — install the gem and write an echo bot
+2. [Code basics](code-basics.md) — the `App`, handlers, and the activity context
+3. [Running in Teams](running-in-teams.md) — registration, tunnel, manifest, troubleshooting

data/docs/getting-started/code-basics.md

@@ -0,0 +1,61 @@
+# Code basics
+
+The quickstart's `config.ru` is a complete Teams app. Here's what each piece does, and the concepts you'll use everywhere else.
+
+## The App
+
+```ruby
+teams = Teams::App.new
+```
+
+`Teams::App` is the heart of the SDK — it owns the route table, the API client, token management, and inbound request validation. By default it reads `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID` from the environment; every option can also be passed explicitly ([App basics](../essentials/app-basics.md) lists them all).
+
+## Handlers
+
+```ruby
+teams.on_message do |ctx|
+  ctx.typing
+  ctx.reply "echo: #{ctx.activity.text}"
+end
+```
+
+Handlers register against activity routes: `on_message` for messages (optionally filtered by a pattern), `on_dialog_open` for dialog invokes, `on_message_ext_query` for message extension searches, and so on — [Listening to activities](../essentials/on-activity.md) has the full list. Multiple handlers can match one activity; a handler with a second block parameter controls chaining:
+
+```ruby
+teams.use do |ctx, nxt|
+  puts "inbound #{ctx.activity.type}"
+  nxt.call   # continue to the next matching handler
+end
+```
+
+## The activity context
+
+Every handler receives a `ctx` with everything about the current activity:
+
+| Member | What it is |
+|---|---|
+| `ctx.activity` | The inbound activity model — `type`, `text`, `from`, `conversation`, `value`, plus raw payload access via `ctx.activity.raw` |
+| `ctx.ref` | The conversation reference — persist `ctx.ref.to_h` to message this conversation later |
+| `ctx.post` / `ctx.reply` / `ctx.quote` / `ctx.update` / `ctx.typing` | Sending — see [Sending messages](../essentials/sending-messages.md) |
+| `ctx.stream` | Chunked streaming responses — see [Streaming](../in-depth-guides/streaming.md) |
+| `ctx.sign_in` / `ctx.sign_out` | User OAuth — see [User authentication](../in-depth-guides/user-authentication.md) |
+| `ctx.api` | The low-level [API client](../essentials/api-client.md) |
+| `ctx.app_graph` / `ctx.user_graph` | [Microsoft Graph](../essentials/graph.md) clients |
+| `ctx.storage`, `ctx.log` | The app's state store and logger |
+
+## The Rack endpoint
+
+```ruby
+run teams.to_rack
+```
+
+`to_rack` returns a plain Rack app serving the Teams messaging endpoint (default `/api/messages`) — mount it in `config.ru`, or route to it from Rails:
+
+```ruby
+# config/routes.rb
+post "/api/messages" => TEAMS_BOT.to_rack
+```
+
+## One naming note
+
+The Microsoft SDKs call their send operation `send`; Ruby uses `post` because `Object#send` is core Ruby. Treat `post` as Ruby's spelling of SDK `send` — including its update-when-id-present behavior. `reply` keeps full SDK reply semantics (reply threading plus Teams quoted-reply markup).

data/docs/getting-started/quickstart.md

@@ -0,0 +1,54 @@
+# Quickstart
+
+Build and run your first Teams bot in Ruby.
+
+## Prerequisites
+
+- Ruby 4.0+
+- A Microsoft 365 tenant where you can register a Teams app ([developer program](https://developer.microsoft.com/microsoft-365/dev-program) tenants work)
+- A tunnel for local development ([Dev Tunnels](https://learn.microsoft.com/azure/developer/dev-tunnels/get-started), ngrok, or similar)
+
+## Install
+
+Add the gem to your project:
+
+```ruby
+# Gemfile
+gem "teams_rb"
+```
+
+```sh
+bundle install
+```
+
+## Your first bot
+
+Create a `config.ru`:
+
+```ruby
+require "teams"
+
+teams = Teams::App.new
+
+teams.on_message do |ctx|
+  ctx.typing
+  ctx.reply "echo: #{ctx.activity.text}"
+end
+
+run teams.to_rack
+```
+
+And run it:
+
+```sh
+CLIENT_ID=... CLIENT_SECRET=... TENANT_ID=... bundle exec rackup -p 3978 -o 0.0.0.0
+```
+
+The app listens for Teams activities on `POST /api/messages`, validates every inbound request against Microsoft's signing keys, and echoes any message back as a quoted reply.
+
+The three environment variables come from your bot registration — [Running in Teams](running-in-teams.md) walks through creating one and connecting Teams to your locally running bot. For local experiments without credentials, `Teams::App.new(skip_auth: true)` disables inbound validation (never use it beyond local testing; the app logs a loud warning when you do).
+
+## Where to go next
+
+- [Code basics](code-basics.md) — what each part of this file does
+- [Running in Teams](running-in-teams.md) — see it live inside the Teams client

data/docs/getting-started/running-in-teams.md

@@ -0,0 +1,44 @@
+# Running in Teams
+
+Connect your locally running bot to a real Teams client.
+
+## 1. Register a bot
+
+Create a Teams app with a bot in the [Teams Developer Portal](https://dev.teams.microsoft.com) (or with Microsoft's Teams CLI). You need three values for the app's environment:
+
+- `CLIENT_ID` — the bot's Microsoft App ID
+- `CLIENT_SECRET` — a client secret for that app registration
+- `TENANT_ID` — your Entra tenant ID (single-tenant bots)
+
+> If you plan to use [user authentication](../in-depth-guides/user-authentication.md), register the bot as an **Azure Bot resource** from the start (Azure portal → Create resource → Azure Bot → "Use existing app registration"). OAuth connection settings only exist there, and converting a Developer Portal registration later means deleting and recreating it.
+
+## 2. Start a tunnel
+
+Teams must reach your machine over HTTPS. With Dev Tunnels:
+
+```sh
+devtunnel create teams-bot -a
+devtunnel port create teams-bot -p 3978
+devtunnel host teams-bot
+```
+
+Note the tunnel URL, e.g. `https://abc123-3978.euw.devtunnels.ms`. Dev Tunnels URLs are stable across restarts, so this is one-time setup.
+
+## 3. Point the bot at the tunnel
+
+In the bot registration, set the **messaging endpoint** to `https://<your-tunnel>/api/messages`, and make sure the **Microsoft Teams channel** is enabled.
+
+## 4. Run and install
+
+```sh
+bundle exec rackup -p 3978 -o 0.0.0.0
+```
+
+Install the app in Teams (Developer Portal → Preview in Teams) and send it a message. Inbound requests are JWT-validated with your real credentials — no `skip_auth` needed behind a tunnel.
+
+## Troubleshooting
+
+- **No response in Teams**: check the messaging endpoint URL, the Teams channel, and that the tunnel and server are both running. The app logs every inbound activity at debug level and every rejected request at warn level.
+- **401s in your logs**: the requests are reaching you but failing validation — usually a `CLIENT_ID`/`TENANT_ID` mismatch with the registration.
+- **Teams caches aggressively**: after manifest changes, fully quit and reopen the Teams client.
+- **At-least-once delivery**: Bot Framework redelivers activities when your bot errors or responds slowly. If a handler's side effects must not repeat, deduplicate by `ctx.activity.id`.

data/docs/in-depth-guides/README.md

@@ -0,0 +1,14 @@
+# In-depth guides
+
+Feature guides for building richer Teams apps:
+
+- [Adaptive Cards](adaptive-cards.md) — the generated card classes, actions, submissions
+- [Dialogs](dialogs.md) — task modules: opening, submissions, multi-step forms
+- [Message extensions](message-extensions.md) — search commands, action commands, link unfurling
+- [Feedback](feedback.md) — thumbs up/down on bot messages
+- [Message reactions](message-reactions.md) — sending and receiving reactions
+- [Streaming](streaming.md) — chunked responses, informative updates, events, typed errors
+- [User authentication](user-authentication.md) — OAuth sign-in, token exchange, Azure setup
+- [Tabs and remote functions](tabs.md) — calling the bot backend from a tab with SSO
+- [Meeting events](meeting-events.md) — meeting start/end
+- [Observability](observability.md) — logging and middleware