docs: fix content gaps, CI detection, and logging (#2808)

## Summary
- fill in missing SubmitData + sub-route handler sections for TS/Python
executing-actions page. C# gets N/A with its own "Server Handlers"
structure since it doesn't have sub-routing
- fix deploy workflow — `NODE_ENV=production` was on a separate
`generate:docs` step, then `npm run build` re-ran it via `prebuild`
without the env var, overwriting prod output with `[Dev]` markers. moved
env to the build step
- fix generate script production codepath — it silently skipped missing
sections without tracking them in `contentGapsManifest`, so the exit
check never fired
- clean up Python logging docs (no custom logger injection, just
standard logging with optional `ConsoleFormatter`)
- move child-logger heading into language includes so it only shows for
TS
- nuke blank observability index page
- add devblogs links to blog posts

## Test plan
- [ ] `NODE_ENV=production npm run generate:docs` passes with 0 content
gaps
- [ ] C# executing-actions page shows "Server Handlers" without
SubmitData/routing sections
- [ ] TS/Python executing-actions pages show full Routing & Handlers
section
- [ ] Python logging page doesn't mention custom logger injection
- [ ] Child Loggers heading only appears on TS logging page

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: heyitsaamir

.github/workflows/deploy-teams-docs.yml

@@ -55,6 +55,8 @@ jobs:
 
       - name: Build static site
         working-directory: teams.md
+        env:
+          NODE_ENV: production
         run: npm run build
 
       - name: Setup GitHub Pages

teams.md/blog/2026-04-28-teams-cli-preview/index.md

@@ -19,6 +19,10 @@ tags: [teams-sdk, cli, preview, announcement, skills]
 description: Introducing the teams-dev agent skill and the Teams CLI v3 Preview for registering and building Teams agents.
 ---
 
+:::info
+This post is also available on the [Microsoft 365 Developer Blog](https://devblogs.microsoft.com/microsoft365dev/from-prompt-to-production-teams-agent-setup-simplified/).
+:::
+
 You want to build a Teams agent. Maybe it answers customer questions from a knowledge base. Maybe it runs your team's standups. The interesting part is the logic, the thing the agent actually *does*.
 
 But before you write a single line of that logic, you have to register it with Teams. That takes a number of steps.

teams.md/scripts/generate-language-docs.ts

@@ -175,16 +175,41 @@ function processLanguageIncludeTags(
       if (isProduction && targetLanguage) {
         const inclPath = getIncludeFilePath(templatePath, targetLanguage);
         if (!fs.existsSync(inclPath)) {
-          // Skip missing content (prod)
+          // Track missing include file as a content gap
+          const gapKey = normalizePath(path.relative(TEMPLATES_DIR, templatePath));
+          if (!contentGapsManifest[gapKey]) {
+            contentGapsManifest[gapKey] = {};
+          }
+          if (!contentGapsManifest[gapKey][sectionName]) {
+            contentGapsManifest[gapKey][sectionName] = [];
+          }
+          if (!contentGapsManifest[gapKey][sectionName].includes(targetLanguage)) {
+            contentGapsManifest[gapKey][sectionName].push(targetLanguage);
+          }
           return '';
         }
 
         try {
           const fileContent = readFileUtf8Normalized(inclPath);
           const sectionContent = extractSection(fileContent, sectionName);
 
-          if (sectionContent === null || sectionContent === '' || sectionContent === 'EMPTY_SECTION') {
-            // Skip missing sections (null), intentional N/A content (empty string), or empty sections
+          if (sectionContent === '') {
+            // Intentional N/A content - skip without tracking as a gap
+            return '';
+          }
+
+          if (sectionContent === null || sectionContent === 'EMPTY_SECTION') {
+            // Track missing/empty sections as content gaps
+            const gapKey = normalizePath(path.relative(TEMPLATES_DIR, templatePath));
+            if (!contentGapsManifest[gapKey]) {
+              contentGapsManifest[gapKey] = {};
+            }
+            if (!contentGapsManifest[gapKey][sectionName]) {
+              contentGapsManifest[gapKey][sectionName] = [];
+            }
+            if (!contentGapsManifest[gapKey][sectionName].includes(targetLanguage)) {
+              contentGapsManifest[gapKey][sectionName].push(targetLanguage);
+            }
             return '';
           }
 

teams.md/src/components/include/in-depth-guides/adaptive-cards/executing-actions/csharp.incl.md

@@ -192,7 +192,13 @@ private static AdaptiveCard CreateProfileCardWithValidation()
 }
 ```
 
-<!-- server-handler-example -->
+<!-- handlers-section -->
+
+## Server Handlers
+
+### Basic Structure
+
+Card actions arrive as `card.action` activities in your app. These give you access to the validated input values plus any `data` values you had configured to be sent back to you.
 
 ```csharp
 using System.Text.Json;
@@ -286,8 +292,6 @@ teams.OnAdaptiveCardAction(async (context, cancellationToken) =>
 });
 ```
 
-<!-- data-typing-note -->
-
 :::note
 The `data` values come from JSON and need to be extracted using the helper method shown above to handle different JSON element types.
 :::

teams.md/src/components/include/in-depth-guides/adaptive-cards/executing-actions/python.incl.md

@@ -103,7 +103,66 @@ def create_profile_card_input_validation():
     return card
 ```
 
-<!-- server-handler-example -->
+<!-- handlers-section -->
+
+## Routing & Handlers
+
+### Using SubmitData
+
+The SDK provides a `SubmitData` helper that sets the routing key for your action. This is the recommended way to wire up actions to specific handlers:
+
+```python
+from microsoft_teams.cards import ExecuteAction, SubmitData
+# ...
+
+ExecuteAction(title="Submit Feedback") \
+    .with_data(SubmitData("submit_feedback")) \
+    .with_associated_inputs("auto")
+
+# You can also pass extra static data alongside the action name
+ExecuteAction(title="Save") \
+    .with_data(SubmitData("save_profile", {"entity_id": "12345"})) \
+    .with_associated_inputs("auto")
+```
+
+`SubmitData` sets a reserved `action` key in the card's data payload. When the user clicks the button, the SDK router reads this key to dispatch to the matching handler.
+
+### Action-Specific Handlers
+
+Register handlers for specific actions. When you use `SubmitData` to set the action name on the card, the SDK routes directly to the matching handler:
+
+```python
+from microsoft_teams.apps import App, ActivityContext
+from microsoft_teams.api import AdaptiveCardInvokeActivity, AdaptiveCardActionMessageResponse, AdaptiveCardInvokeResponse
+# ...
+
+# 'submit_feedback' matches the identifier passed to SubmitData('submit_feedback')
+@app.on_card_action_execute("submit_feedback")
+async def handle_submit_feedback(ctx: ActivityContext[AdaptiveCardInvokeActivity]) -> AdaptiveCardInvokeResponse:
+    data = ctx.activity.value.action.data
+    await ctx.send(f"Feedback received: {data.get('feedback')}")
+    return AdaptiveCardActionMessageResponse(
+        status_code=200,
+        type="application/vnd.microsoft.activity.message",
+        value="Action processed successfully",
+    )
+
+@app.on_card_action_execute("save_profile")
+async def handle_save_profile(ctx: ActivityContext[AdaptiveCardInvokeActivity]) -> AdaptiveCardInvokeResponse:
+    data = ctx.activity.value.action.data
+    await ctx.send(f"Profile saved!\nName: {data.get('name')}\nEmail: {data.get('email')}")
+    return AdaptiveCardActionMessageResponse(
+        status_code=200,
+        type="application/vnd.microsoft.activity.message",
+        value="Action processed successfully",
+    )
+```
+
+The decorator argument matches the value passed to `SubmitData`. This is cleaner than a catch-all with a switch statement, and scales better as you add more actions.
+
+### Catch-All Handler
+
+If you need to handle all card actions in one place, you can use the catch-all handler:
 
 ```python
 from microsoft_teams.api import AdaptiveCardInvokeActivity, AdaptiveCardActionErrorResponse, AdaptiveCardActionMessageResponse, HttpError, InnerHttpError, AdaptiveCardInvokeResponse
@@ -158,8 +217,6 @@ async def handle_card_action(ctx: ActivityContext[AdaptiveCardInvokeActivity]) -
     )
 ```
 
-<!-- data-typing-note -->
-
 :::note
 The `data` values are accessible as a dictionary and can be accessed using `.get()` method for safe access.
 :::

teams.md/src/components/include/in-depth-guides/adaptive-cards/executing-actions/typescript.incl.md

@@ -122,7 +122,65 @@ function createProfileCardInputValidation() {
 }
 ```
 
-<!-- server-handler-example -->
+<!-- handlers-section -->
+
+## Routing & Handlers
+
+### Using SubmitData
+
+The SDK provides a `SubmitData` helper that sets the routing key for your action. This is the recommended way to wire up actions to specific handlers:
+
+```typescript
+import { ExecuteAction, SubmitData } from '@microsoft/teams.cards';
+// ...
+
+new ExecuteAction({ title: 'Submit Feedback' })
+  .withData(new SubmitData('submit_feedback'))
+  .withAssociatedInputs('auto')
+
+// You can also pass extra static data alongside the action name
+new ExecuteAction({ title: 'Save' })
+  .withData(new SubmitData('save_profile', { entityId: '12345' }))
+  .withAssociatedInputs('auto')
+```
+
+`SubmitData` sets a reserved `action` key in the card's data payload. When the user clicks the button, the SDK router reads this key to dispatch to the matching handler.
+
+### Action-Specific Handlers
+
+Register handlers for specific actions. When you use `SubmitData` to set the action name on the card, the SDK routes directly to the matching handler:
+
+```typescript
+import { App } from '@microsoft/teams.apps';
+// ...
+
+// 'submit_feedback' matches the identifier passed to SubmitData('submit_feedback')
+app.on('card.action.submit_feedback', async ({ activity, send }) => {
+  const data = activity.value.action.data;
+  await send(`Feedback received: ${data.feedback}`);
+  return {
+    statusCode: 200,
+    type: 'application/vnd.microsoft.activity.message',
+    value: 'Action processed successfully',
+  };
+});
+
+app.on('card.action.save_profile', async ({ activity, send }) => {
+  const data = activity.value.action.data;
+  await send(`Profile saved!\nName: ${data.name}\nEmail: ${data.email}`);
+  return {
+    statusCode: 200,
+    type: 'application/vnd.microsoft.activity.message',
+    value: 'Action processed successfully',
+  };
+});
+```
+
+The route name follows the pattern `card.action.<action-name>`, where `<action-name>` matches the value passed to `SubmitData`. This is cleaner than a catch-all with a switch statement, and scales better as you add more actions.
+
+### Catch-All Handler
+
+If you need to handle all card actions in one place, you can use the catch-all handler:
 
 ```typescript
 import {
@@ -189,8 +247,6 @@ app.on('card.action', async ({ activity, send }) => {
 });
 ```
 
-<!-- data-typing-note -->
-
 :::note
 The `data` values are not typed and come as `any`, so you will need to cast them to the correct type in this case.
 :::

teams.md/src/components/include/in-depth-guides/observability/logging/python.incl.md

@@ -1,41 +1,26 @@
 <!-- default-logger -->
 
-Python's standard `logging` module (configured with `ConsoleFormatter` from the SDK).
+Python's standard `logging` module, using `logging.getLogger(__name__)` per module.
 
 <!-- package-name -->
 
 `microsoft-teams-common`
 
 <!-- custom-logger-example -->
 
-The Python SDK writes to the standard `logging` module. Configure a handler and formatter at startup:
+The Python SDK uses standard `logging` — there's no custom logger to inject into `App`. To see SDK log output, attach a handler to the `microsoft_teams` logger hierarchy. The SDK ships a `ConsoleFormatter` with color-coded output if you want it:
 
 ```python
-import asyncio
 import logging
-
-from microsoft_teams.api import MessageActivity
-from microsoft_teams.apps import ActivityContext, App
+import os
 from microsoft_teams.common import ConsoleFormatter
 
-# Setup logging
-logging.getLogger().setLevel(logging.DEBUG)
-stream_handler = logging.StreamHandler()
-stream_handler.setFormatter(ConsoleFormatter())
-logging.getLogger().addHandler(stream_handler)
-logger = logging.getLogger(__name__)
-
-app = App()
-
-
-@app.on_message
-async def handle_message(ctx: ActivityContext[MessageActivity]):
-    logger.debug(ctx.activity)
-    await ctx.send(f"You said '{ctx.activity.text}'")
-
-
-if __name__ == "__main__":
-    asyncio.run(app.start())
+handler = logging.StreamHandler()
+handler.setFormatter(ConsoleFormatter())
+logging.getLogger("microsoft_teams").addHandler(handler)
+logging.getLogger("microsoft_teams").setLevel(
+    os.getenv("LOG_LEVEL", "INFO").upper()
+)
 ```
 
 <!-- log-levels -->
@@ -55,6 +40,10 @@ handler.addFilter(ConsoleFilter("microsoft_teams*"))  # only SDK loggers
 logging.getLogger().addHandler(handler)
 ```
 
+<!-- child-logger -->
+
+N/A
+
 <!-- env-vars -->
 
 The Python SDK does not read logging environment variables on its own. If you want `LOG_LEVEL` to control verbosity, read it yourself at startup:

teams.md/src/components/include/in-depth-guides/observability/logging/typescript.incl.md

@@ -57,6 +57,8 @@ Env vars override options passed to the constructor. If you do not pass a logger
 
 <!-- child-logger -->
 
+## Child Loggers
+
 Call `log.child('scope')` on an existing logger to get a scoped logger. Its name is `parent/scope`, and pattern/level are inherited.
 
 ```typescript

teams.md/src/pages/templates/in-depth-guides/adaptive-cards/executing-actions.mdx

@@ -60,26 +60,4 @@ Input Controls provide ways for you to validate. More details can be found on th
 
 <LanguageInclude section="input-validation-example" />
 
-## Routing & Handlers
-
-### Using SubmitData
-
-The SDK provides a `SubmitData` helper that sets the routing key for your action. This is the recommended way to wire up actions to specific handlers:
-
-<LanguageInclude section="submit-data-example" />
-
-### Action-Specific Handlers
-
-Register handlers for specific actions. When you use `SubmitData` to set the action name on the card, the SDK routes directly to the matching handler:
-
-<LanguageInclude section="sub-route-handler-example" />
-
-This is cleaner than a catch-all with a switch statement, and scales better as you add more actions.
-
-### Catch-All Handler
-
-If you need to handle all card actions in one place, you can use the catch-all handler:
-
-<LanguageInclude section="server-handler-example" />
-
-<LanguageInclude section="data-typing-note" />
+<LanguageInclude section="handlers-section" />