docs(teams): split meetings setup from operator runbook

website/docs/guides/operate-teams-meeting-pipeline.md

@@ -0,0 +1,193 @@
+---
+title: "Operate the Teams Meeting Pipeline"
+description: "Runbook, go-live checklist, and operator worksheet for the Microsoft Teams meeting pipeline"
+---
+
+# Operate the Teams Meeting Pipeline
+
+Use this guide after you have already enabled the feature from [Teams Meetings](/docs/user-guide/messaging/teams-meetings).
+
+This page covers:
+- operator CLI flows
+- routine subscription maintenance
+- failure triage
+- go-live checks
+- rollout worksheet
+
+## Core Operator Commands
+
+### Validate the config snapshot
+
+```bash
+hermes teams-pipeline validate
+```
+
+Use this first after any config change.
+
+### Inspect token health
+
+```bash
+hermes teams-pipeline token-health
+hermes teams-pipeline token-health --force-refresh
+```
+
+Use `--force-refresh` when you suspect stale auth state.
+
+### Inspect subscriptions
+
+```bash
+hermes teams-pipeline subscriptions
+```
+
+### Renew near-expiry subscriptions
+
+```bash
+hermes teams-pipeline maintain-subscriptions
+hermes teams-pipeline maintain-subscriptions --dry-run
+```
+
+### Inspect recent jobs
+
+```bash
+hermes teams-pipeline list
+hermes teams-pipeline list --status failed
+hermes teams-pipeline show <job-id>
+```
+
+### Replay a stored job
+
+```bash
+hermes teams-pipeline run <job-id>
+```
+
+### Dry-run meeting artifact fetches
+
+```bash
+hermes teams-pipeline fetch --meeting-id <meeting-id>
+hermes teams-pipeline fetch --join-web-url "<join-url>"
+```
+
+## Routine Runbook
+
+### After first setup
+
+Run these in order:
+
+```bash
+hermes teams-pipeline validate
+hermes teams-pipeline token-health --force-refresh
+hermes teams-pipeline subscriptions
+```
+
+Then trigger or wait for a real meeting event and confirm:
+
+```bash
+hermes teams-pipeline list
+hermes teams-pipeline show <job-id>
+```
+
+### Daily or periodic checks
+
+- run `hermes teams-pipeline maintain-subscriptions --dry-run`
+- inspect `hermes teams-pipeline list --status failed`
+- verify the Teams delivery target is still the correct chat or channel
+
+### Before changing webhook URLs or delivery targets
+
+- update the public notification URL or Teams target config
+- run `hermes teams-pipeline validate`
+- renew or recreate affected subscriptions
+- confirm new events land in the expected sink
+
+## Failure Triage
+
+### No jobs are being created
+
+Check:
+- `msgraph_webhook` is enabled
+- the public notification URL points to `/msgraph/webhook`
+- the client state in the subscription matches `MSGRAPH_WEBHOOK_CLIENT_STATE`
+- subscriptions still exist remotely and are not expired
+
+### Jobs stay in retry or fail before summarization
+
+Check:
+- transcript permissions and availability
+- recording permissions and artifact availability
+- `ffmpeg` availability if recording fallback is enabled
+- Graph token health
+
+### Summaries are produced but not delivered to Teams
+
+Check:
+- `platforms.teams.enabled: true`
+- `delivery_mode`
+- `incoming_webhook_url` for webhook mode
+- `chat_id` or `team_id` plus `channel_id` for Graph mode
+- Teams auth config if Graph posting is used
+
+### Duplicate or unexpected replays
+
+Check:
+- whether you manually replayed a job with `hermes teams-pipeline run`
+- whether the sink record already exists for that meeting
+- whether you intentionally enabled a resend path in your local config
+
+## Go-Live Checklist
+
+- [ ] Graph credentials are present and correct
+- [ ] `msgraph_webhook` is enabled and reachable from the public internet
+- [ ] `MSGRAPH_WEBHOOK_CLIENT_STATE` is set and matches subscriptions
+- [ ] transcript subscription is created
+- [ ] recording subscription is created if STT fallback is required
+- [ ] `ffmpeg` is installed if recording fallback is enabled
+- [ ] Teams outbound delivery target is configured and verified
+- [ ] Notion and Linear sinks are configured only if actually needed
+- [ ] `hermes teams-pipeline validate` returns an OK snapshot
+- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds
+- [ ] a real end-to-end meeting event has produced a stored job
+- [ ] at least one summary has reached the intended delivery sink
+
+## Delivery-Mode Decision Guide
+
+| Mode | Use when | Tradeoff |
+|------|----------|----------|
+| `incoming_webhook` | you only need simple posting into Teams | simplest setup, less control |
+| `graph` | you need channel or chat posting through Graph | more control, more auth and target config |
+
+## Operator Worksheet
+
+Fill this out before rollout:
+
+| Item | Value |
+|------|-------|
+| Public notification URL | |
+| Graph tenant ID | |
+| Graph client ID | |
+| Webhook client state | |
+| Transcript resource subscription | |
+| Recording resource subscription | |
+| Teams delivery mode | |
+| Teams chat ID or team/channel | |
+| Notion database ID | |
+| Linear team ID | |
+| Store path override, if any | |
+| Owner for daily checks | |
+
+## Change Review Worksheet
+
+Use this before changing the deployment:
+
+| Question | Answer |
+|----------|--------|
+| Are we changing the public webhook URL? | |
+| Are we rotating Graph credentials? | |
+| Are we changing Teams delivery mode? | |
+| Are we moving to a new Teams chat or channel? | |
+| Do subscriptions need to be recreated or renewed? | |
+| Do we need a fresh end-to-end verification run? | |
+
+## Related Docs
+
+- [Teams Meetings setup](/docs/user-guide/messaging/teams-meetings)
+- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams)

website/docs/user-guide/messaging/index.md

@@ -427,5 +427,6 @@ Each platform has its own toolset:
 - [QQBot Setup](qqbot.md)
 - [Yuanbao Setup](yuanbao.md)
 - [Microsoft Teams Setup](teams.md)
+- [Teams Meetings Pipeline](teams-meetings.md)
 - [Open WebUI + API Server](open-webui.md)
 - [Webhooks](webhooks.md)

website/docs/user-guide/messaging/teams-meetings.md

@@ -0,0 +1,227 @@
+---
+sidebar_position: 6
+title: "Teams Meetings"
+description: "Set up the Microsoft Teams meeting summary pipeline with Microsoft Graph webhooks"
+---
+
+# Microsoft Teams Meetings
+
+Use the Teams meeting pipeline when you want Hermes to ingest Microsoft Graph meeting events, fetch transcripts first, fall back to recordings plus STT when needed, and deliver a structured summary to downstream sinks.
+
+This page focuses on setup and enablement:
+- Graph credentials
+- webhook listener configuration
+- Teams delivery modes
+- pipeline config shape
+
+For day-2 operations, go-live checks, and the operator worksheet, use the dedicated guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline).
+
+## What This Feature Does
+
+The pipeline:
+1. receives Microsoft Graph webhook events
+2. resolves the meeting and prefers transcript artifacts first
+3. falls back to recording download plus STT when no usable transcript is available
+4. stores durable job state and sink records locally
+5. can write summaries to Notion, Linear, and Microsoft Teams
+
+Operator actions stay in the CLI:
+
+```bash
+hermes teams-pipeline validate
+hermes teams-pipeline list
+hermes teams-pipeline maintain-subscriptions
+```
+
+## Prerequisites
+
+Before enabling the meetings pipeline, make sure you have:
+
+- a working Hermes install
+- the existing [Microsoft Teams bot setup](/docs/user-guide/messaging/teams) if you want Teams outbound delivery
+- Microsoft Graph application credentials with the permissions required for the meeting resources you plan to subscribe to
+- a public HTTPS URL that Microsoft Graph can call for webhook delivery
+- `ffmpeg` installed if you want recording-plus-STT fallback
+
+## Step 1: Add Microsoft Graph Credentials
+
+Add Graph app-only credentials to `~/.hermes/.env`:
+
+```bash
+MSGRAPH_TENANT_ID=<tenant-id>
+MSGRAPH_CLIENT_ID=<client-id>
+MSGRAPH_CLIENT_SECRET=<client-secret>
+```
+
+These credentials are used by:
+- the Graph client foundation
+- subscription maintenance commands
+- meeting resolution and artifact fetches
+- Graph-based Teams outbound delivery when you do not provide a dedicated Teams access token
+
+## Step 2: Enable the Graph Webhook Listener
+
+The webhook listener is a gateway platform named `msgraph_webhook`. At minimum, enable it and set a client state value:
+
+```bash
+MSGRAPH_WEBHOOK_ENABLED=true
+MSGRAPH_WEBHOOK_PORT=8646
+MSGRAPH_WEBHOOK_CLIENT_STATE=<random-shared-secret>
+MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
+```
+
+The listener exposes:
+- `/msgraph/webhook` for Graph notifications
+- `/health` for a simple health check
+
+You need to route your public HTTPS endpoint to that listener. For example, if your public domain is `https://ops.example.com`, your Graph notification URL would typically be:
+
+```text
+https://ops.example.com/msgraph/webhook
+```
+
+## Step 3: Configure Teams Delivery and Pipeline Behavior
+
+The meeting pipeline reads its runtime config from the existing `teams` platform entry. Pipeline-specific knobs live under `teams.extra.meeting_pipeline`. Teams outbound delivery stays on the normal Teams platform config surface.
+
+Example `~/.hermes/config.yaml`:
+
+```yaml
+platforms:
+  msgraph_webhook:
+    enabled: true
+    extra:
+      port: 8646
+      client_state: "replace-me"
+      accepted_resources:
+        - "communications/onlineMeetings"
+
+  teams:
+    enabled: true
+    extra:
+      client_id: "your-teams-client-id"
+      client_secret: "your-teams-client-secret"
+      tenant_id: "your-teams-tenant-id"
+
+      # outbound summary delivery
+      delivery_mode: "graph" # or incoming_webhook
+      team_id: "team-id"
+      channel_id: "channel-id"
+      # incoming_webhook_url: "https://..."
+
+      meeting_pipeline:
+        transcript_min_chars: 80
+        transcript_required: false
+        transcription_fallback: true
+        ffmpeg_extract_audio: true
+        notion:
+          enabled: false
+        linear:
+          enabled: false
+```
+
+## Teams Delivery Modes
+
+The pipeline supports two Teams summary-delivery modes inside the existing Teams plugin.
+
+### `incoming_webhook`
+
+Use this when you want a simple webhook post into Teams without channel-message creation through Graph.
+
+Required config:
+
+```yaml
+platforms:
+  teams:
+    enabled: true
+    extra:
+      delivery_mode: "incoming_webhook"
+      incoming_webhook_url: "https://..."
+```
+
+### `graph`
+
+Use this when you want Hermes to post the summary through Microsoft Graph into a Teams chat or channel.
+
+Supported targets:
+- `chat_id`
+- `team_id` + `channel_id`
+- `team_id` + `home_channel` fallback for the existing Teams platform
+
+Example:
+
+```yaml
+platforms:
+  teams:
+    enabled: true
+    extra:
+      delivery_mode: "graph"
+      team_id: "team-id"
+      channel_id: "channel-id"
+```
+
+## Step 4: Start the Gateway
+
+Start Hermes normally after updating config:
+
+```bash
+hermes gateway run
+```
+
+Or, if you run Hermes in Docker, start the gateway the same way you already do for your deployment.
+
+Check the listener:
+
+```bash
+curl http://localhost:8646/health
+```
+
+## Step 5: Create Graph Subscriptions
+
+Use the plugin CLI to create and inspect subscriptions.
+
+Examples:
+
+```bash
+hermes teams-pipeline subscribe \
+  --resource communications/onlineMeetings/getAllTranscripts \
+  --notification-url https://ops.example.com/msgraph/webhook \
+  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
+
+hermes teams-pipeline subscribe \
+  --resource communications/onlineMeetings/getAllRecordings \
+  --notification-url https://ops.example.com/msgraph/webhook \
+  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
+```
+
+For subscription maintenance and day-2 operator flows, continue with the guide: [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline).
+
+## Validation
+
+Run the built-in validation snapshot:
+
+```bash
+hermes teams-pipeline validate
+```
+
+Useful companion checks:
+
+```bash
+hermes teams-pipeline token-health
+hermes teams-pipeline subscriptions
+```
+
+## Troubleshooting
+
+| Problem | What to check |
+|---------|---------------|
+| Graph webhook validation fails | Confirm the public URL is correct and reachable, and that Graph is calling the exact `/msgraph/webhook` path |
+| Jobs do not appear in `hermes teams-pipeline list` | Confirm `msgraph_webhook` is enabled and that subscriptions point at the right notification URL |
+| Transcript-first never succeeds | Check Graph permissions for transcript resources and whether the transcript artifact exists for that meeting |
+| Recording fallback fails | Confirm `ffmpeg` is installed and the Graph app can access recording artifacts |
+| Teams summary delivery fails | Re-check `delivery_mode`, target IDs, and Teams auth config |
+
+## Related Docs
+
+- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams)
+- [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline)

website/docs/user-guide/messaging/teams.md

@@ -8,6 +8,8 @@ description: "Set up Hermes Agent as a Microsoft Teams bot"
 
 Connect Hermes Agent to Microsoft Teams as a bot. Unlike Slack's Socket Mode, Teams delivers messages by calling a **public HTTPS webhook**, so your instance needs a publicly reachable endpoint — either a dev tunnel (local dev) or a real domain (production).
 
+Need meeting summaries from Microsoft Graph events rather than normal bot conversations? Use the dedicated setup page: [Teams Meetings](/docs/user-guide/messaging/teams-meetings).
+
 ## How the Bot Responds
 
 | Context | Behavior |
@@ -243,3 +245,8 @@ Treat `TEAMS_CLIENT_SECRET` like a password — rotate it periodically via the A
 - Store credentials in `~/.hermes/.env` with permissions `600` (`chmod 600 ~/.hermes/.env`)
 - The bot only accepts messages from users in `TEAMS_ALLOWED_USERS`; unauthorized messages are silently dropped
 - Your public endpoint (`/api/messages`) is authenticated by the Teams Bot Framework — requests without valid JWTs are rejected
+
+## Related Docs
+
+- [Teams Meetings](/docs/user-guide/messaging/teams-meetings)
+- [Operate the Teams Meeting Pipeline](/docs/guides/operate-teams-meeting-pipeline)