@yemi33/minions 0.1.812 → 0.1.814

package/CHANGELOG.md

@@ -1,8 +1,10 @@
 # Changelog
 
-## 0.1.812 (2026-04-11)
+## 0.1.814 (2026-04-11)
 
 ### Features
+-  Bidirectional Teams integration for Command Center (#764)
+- show branch strategy on PRD view (#762)
 - Restructure decompose.md sub-task output format (#655)
 -  CC race condition fixes, doc-chat expand, settings save fix, metric rate
 -  configurable ignored comment authors — auto-filtered, never trigger fixes
@@ -11,6 +13,8 @@
 -  cap review→fix cycles at evalMaxIterations (default 3)
 
 ### Fixes
+-  add smoke test for checkTimeouts ReferenceError regression (closes #775) (#822)
+- replace safeWrite with mutateDispatch in CLI kill handler (#654)
 -  CC queue drain uses combined flush, not one-at-a-time while loop (#818)
 -  allow agents to explain rationale instead of blindly fixing review feedback
 -  don't URL-encode ADO branchName filter (refs/heads/ format expected raw)
@@ -29,8 +33,6 @@
 -  never downgrade reviewStatus from 'approved' unless explicitly rejected
 -  warn on invalid pipeline JSON instead of silently dropping + add test
 -  repair invalid JSON in daily-arch-improvement pipeline
--  flush queued CC messages as single combined request
--  human feedback fixes are never capped (only minion review→fix loop is)
 
 ## 0.1.782 (2026-04-10)
 

package/dashboard/js/command-center.js

@@ -378,11 +378,14 @@ async function ccSend() {
   }
   var wasAborted = await _ccDoSend(message);
 
-  // Flush queued messages — combine into single request
-  if (tab._queue && tab._queue.length > 0) {
-    var combined = tab._queue.splice(0).join('\n\n');
+  // Flush queued messages one at a time, pausing after abort to let server release ccInFlight
+  while (tab._queue && tab._queue.length > 0) {
+    if (wasAborted) {
+      await new Promise(function(r) { setTimeout(r, 1500); });
+    }
+    var next = tab._queue.shift();
     _renderQueueIndicator();
-    await _ccDoSend(combined);
+    wasAborted = await _ccDoSend(next);
   }
 }
 

package/dashboard/js/render-prd.js

@@ -171,6 +171,12 @@ function renderPrdProgress(prog) {
     const agentLabel = wiAgent ? '<span style="font-size:9px;color:var(--muted)" title="' + escHtml(wiAgent.name || wi.dispatched_to) + '">' +
       (wiAgent.emoji || '') + ' ' + escHtml(wiAgent.name || wi.dispatched_to) + '</span>' : '';
 
+    // Branch label — show the target branch for this item
+    const wiBranch = wi ? (wi.branch || wi.featureBranch || (wi._artifacts && wi._artifacts.branch) || '') : '';
+    const branchLabel = wiBranch
+      ? '<span style="font-size:9px;color:var(--muted);background:var(--surface);padding:1px 5px;border-radius:3px;border:1px solid var(--border);font-family:monospace;max-width:180px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;display:inline-block;vertical-align:middle" title="Branch: ' + escHtml(wiBranch) + '">&#x1F33F; ' + escHtml(wiBranch) + '</span>'
+      : '';
+
     // Requeue button for failed items or PRD items with no work item (orphaned/deleted)
     const canRequeue = (wi && (wi.status === 'failed' || i.status === 'failed')) ||
       (!wi && i.status && i.status !== 'missing' && i.status !== 'done' && i.status !== 'planned');
@@ -195,6 +201,7 @@ function renderPrdProgress(prog) {
       requeueBtn +
       (projBadges ? '<span>' + projBadges + '</span>' : '') +
       (prLinks ? '<span>' + prLinks + '</span>' : '') +
+      branchLabel +
       '<span class="prd-item-priority ' + (i.priority || '') + '">' + escHtml(i.priority || '') + '</span>' +
       '<span onclick="event.stopPropagation();prdItemRemove(\'' + src + '\',\'' + iid + '\')" style="color:var(--red);cursor:pointer;font-size:10px;padding:0 4px" title="Remove item">x</span>' +
       (i.description ? '<div style="width:100%;font-size:11px;color:var(--muted);padding:2px 0 2px 42px;line-height:1.4">' + renderMd(i.description) + '</div>' : '') +
@@ -283,7 +290,9 @@ function renderPrdProgress(prog) {
     return '<div style="font-size:11px;font-weight:600;color:var(--blue);margin-bottom:4px;padding:6px 8px;background:var(--surface2);border-radius:4px;display:flex;align-items:center;gap:8px;flex-wrap:wrap">' +
       (g._projects.length > 0 ? g._projects.map(function(p) { return '<span class="prd-project-badge">' + escHtml(p) + '</span>'; }).join(' ') : '') +
       '<span style="color:var(--text)">' + escHtml(summary || g.file) + '</span>' +
-      (g.branchStrategy === 'shared-branch' ? '<span style="font-size:9px;padding:1px 5px;border-radius:3px;background:rgba(210,153,34,0.15);color:var(--yellow);font-weight:400">shared branch</span>' : '') +
+      (g.branchStrategy === 'shared-branch'
+        ? '<span style="font-size:9px;padding:1px 5px;border-radius:3px;background:rgba(210,153,34,0.15);color:var(--yellow);font-weight:400" title="All items commit to a single shared feature branch">&#x1F333; shared branch</span>'
+        : '<span style="font-size:9px;padding:1px 5px;border-radius:3px;background:rgba(56,139,253,0.12);color:var(--blue);font-weight:400" title="Each item gets its own branch (work/P-xxx) and PR">&#x1F500; parallel branches</span>') +
       pausedLabel +
       staleLabel +
       '<span style="font-weight:700;font-size:11px;color:' + (done === g.items.length && g.items.length > 0 ? 'var(--green)' : 'var(--text)') + '">' + (g.items.length > 0 ? Math.round((done / g.items.length) * 100) : 0) + '%</span>' +
@@ -400,6 +409,12 @@ function renderPrdProgress(prog) {
               return '<span onclick="event.stopPropagation();prdItemRequeue(\'' + escHtml(rqId) + '\',\'' + escHtml(w ? (w._source || '') : '') + '\',\'' + escHtml(i.source || '') + '\')" style="font-size:8px;color:var(--green);cursor:pointer;padding:1px 4px;background:rgba(63,185,80,0.1);border:1px solid rgba(63,185,80,0.3);border-radius:3px">retry</span>';
             })() +
             (deps ? '<span style="font-size:8px;color:var(--muted)" title="Depends on: ' + escHtml(deps) + '">deps: ' + escHtml(deps) + '</span>' : '') +
+            (function() {
+              var w = wi[i.id];
+              var b = w ? (w.branch || w.featureBranch || (w._artifacts && w._artifacts.branch) || '') : '';
+              if (!b) return '';
+              return '<span style="font-size:8px;color:var(--muted);font-family:monospace;max-width:120px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;display:inline-block;vertical-align:middle" title="Branch: ' + escHtml(b) + '">&#x1F33F; ' + escHtml(b) + '</span>';
+            })() +
           '</div>' +
           ((i.prs || []).length ? '<div style="margin-top:3px">' + (i.prs || []).map(function(pr) { return _renderPrLink(pr, { size: '9px' }); }).join(' ') + '</div>' : '') +
           (i.status === 'decomposed' ? (function() {

package/dashboard.js

@@ -20,6 +20,7 @@ const _dashboardVersion = {
 };
 const shared = require('./engine/shared');
 const queries = require('./engine/queries');
+const teams = require('./engine/teams');
 const os = require('os');
 
 const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS } = shared;
@@ -38,6 +39,7 @@ function reloadConfig() {
 }
 
 const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
+const TEAMS_INBOX_PATH = path.join(ENGINE_DIR, 'teams-inbox.json');
 
 // Resolve a plan/PRD file path: .json files live in prd/, .md files in plans/
 // Validates that the file stays within the expected directory to prevent path traversal.
@@ -2214,6 +2216,9 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
         }, { defaultValue: { pending: [], active: [], completed: [] } });
       }
 
+      // Teams notification for plan approval — non-blocking
+      try { teams.teamsNotifyPlanEvent({ name: plan.plan_summary || body.file, file: body.file }, 'plan-approved').catch(() => {}); } catch {}
+
       invalidateStatusCache();
       return jsonReply(res, 200, { ok: true, status: 'approved', resumedWorkItems: resumed });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
@@ -2422,6 +2427,10 @@ If nothing to do: { "duplicates": [], "reclassify": [], "remove": [] }`;
       plan.rejectedBy = body.rejectedBy || os.userInfo().username;
       if (body.reason) plan.rejectionReason = body.reason;
       safeWrite(planPath, plan);
+
+      // Teams notification for plan rejection — non-blocking
+      try { teams.teamsNotifyPlanEvent({ name: plan.plan_summary || body.file, file: body.file }, 'plan-rejected').catch(() => {}); } catch {}
+
       return jsonReply(res, 200, { ok: true, status: 'rejected' });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
@@ -3442,6 +3451,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           });
         }
 
+        // Mirror CC response to Teams (non-blocking, skip Teams-originated)
+        if (!tabId.startsWith('teams-')) {
+          teams.teamsPostCCResponse(body.message, result.text).catch(() => {});
+        }
+
         const reply = { ...parseCCActions(result.text), sessionId: ccSession.sessionId, newSession: !wasResume };
         if (sessionReset) reply.sessionReset = true;
         return jsonReply(res, 200, reply);
@@ -3555,6 +3569,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const donePayload = { type: 'done', text: displayText, actions, sessionId: responseSessionId, newSession: !wasResume };
         if (sessionReset) donePayload.sessionReset = true;
         res.write('data: ' + JSON.stringify(donePayload) + '\n\n');
+
+        // Mirror CC response to Teams (non-blocking, skip Teams-originated)
+        const _streamTabId = body.tabId || 'default';
+        if (!_streamTabId.startsWith('teams-')) {
+          teams.teamsPostCCResponse(body.message, result.text).catch(() => {});
+        }
+
         _ccStreamEnded = true; res.end();
       } finally {
         ccInFlightTabs.delete(tabId);
@@ -3850,6 +3871,93 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }
   }
 
+  // ── Teams Bot Handler ─────────────────────────────────────────────────────
+
+  async function handleTeamsBot(req, res) {
+    if (!teams.isTeamsEnabled()) {
+      return jsonReply(res, 503, { error: 'Teams integration disabled' }, req);
+    }
+    const adapter = teams.createAdapter();
+    if (!adapter) {
+      return jsonReply(res, 503, { error: 'Teams adapter unavailable' }, req);
+    }
+    try {
+      await adapter.process(req, res, async (context) => {
+        const activity = context.activity;
+        const cfg = teams.getTeamsConfig();
+
+        // Save conversation reference on install/member events
+        if (activity.type === 'conversationUpdate' && activity.membersAdded?.length) {
+          const ref = context.activity.conversation?.id;
+          if (ref) {
+            const convRef = {
+              activityId: activity.id,
+              user: activity.from,
+              bot: activity.recipient,
+              conversation: activity.conversation,
+              channelId: activity.channelId,
+              locale: activity.locale,
+              serviceUrl: activity.serviceUrl,
+            };
+            teams.saveConversationRef(activity.conversation.id, convRef);
+            shared.log('info', `Teams conversationUpdate: saved ref for ${activity.conversation.id}`);
+          }
+        }
+
+        if (activity.type === 'installationUpdate') {
+          const convRef = {
+            activityId: activity.id,
+            user: activity.from,
+            bot: activity.recipient,
+            conversation: activity.conversation,
+            channelId: activity.channelId,
+            locale: activity.locale,
+            serviceUrl: activity.serviceUrl,
+          };
+          if (activity.conversation?.id) {
+            teams.saveConversationRef(activity.conversation.id, convRef);
+            shared.log('info', `Teams installationUpdate: saved ref for ${activity.conversation.id}`);
+          }
+        }
+
+        // Handle incoming messages
+        if (activity.type === 'message' && activity.text) {
+          // Filter bot's own echo messages
+          if (activity.from?.id === cfg.appId) return;
+
+          const msgId = `teams-${Date.now()}-${shared.uid()}`;
+          const convRef = {
+            activityId: activity.id,
+            user: activity.from,
+            bot: activity.recipient,
+            conversation: activity.conversation,
+            channelId: activity.channelId,
+            locale: activity.locale,
+            serviceUrl: activity.serviceUrl,
+          };
+          mutateJsonFileLocked(TEAMS_INBOX_PATH, (inbox) => {
+            if (!Array.isArray(inbox)) inbox = [];
+            inbox.push({
+              id: msgId,
+              text: activity.text,
+              from: activity.from?.name || activity.from?.id || 'unknown',
+              conversationRef: convRef,
+              receivedAt: new Date().toISOString(),
+              _processedAt: null,
+            });
+            return inbox;
+          }, { defaultValue: [] });
+          shared.log('info', `Teams message received from ${activity.from?.name || 'unknown'}: ${activity.text.slice(0, 80)}`);
+        }
+      });
+    } catch (err) {
+      shared.log('warn', `Teams bot handler error: ${err.message}`);
+      if (!res.headersSent) {
+        return jsonReply(res, 500, { error: 'Bot processing failed' }, req);
+      }
+    }
+  }
+
   // ── Route Registry ──────────────────────────────────────────────────────────
   // Order matters: specific routes before general ones (e.g., /api/plans/approve before /api/plans/:file)
 
@@ -4453,6 +4561,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/settings', desc: 'Update engine + claude + agent config', params: 'engine?, claude?, agents?', handler: handleSettingsUpdate },
     { method: 'POST', path: '/api/settings/routing', desc: 'Update routing.md', params: 'content', handler: handleSettingsRouting },
     { method: 'POST', path: '/api/settings/reset', desc: 'Reset engine + claude + agent settings to defaults', handler: handleSettingsReset },
+
+    // Teams Bot Framework webhook
+    { method: 'POST', path: '/api/bot', desc: 'Bot Framework webhook for Teams integration', handler: handleTeamsBot },
   ];
 
   // ── Route Dispatcher ────────────────────────────────────────────────────────

package/docs/teams-production.md

@@ -0,0 +1,368 @@
+# Teams Production Endpoint Migration
+
+Guide for migrating the Minions Teams bot from a Dev Tunnel to a stable public HTTPS endpoint for production use. Choose one of the three deployment options below based on your infrastructure.
+
+**Key fact:** The Azure Bot messaging endpoint URL can be changed at any time in the Azure Portal — it takes effect immediately. No bot reinstallation is needed in Teams. This means you can switch between Dev Tunnel and production endpoints freely.
+
+**Prerequisites:**
+
+- A working Teams integration via Dev Tunnel (see [docs/teams-setup.md](teams-setup.md))
+- Azure CLI installed (`az --version`) for Options 1 and 2
+- A public-facing server or VM for Option 3
+
+---
+
+## Option 1: Azure App Service
+
+Deploy the Minions dashboard as an Azure App Service with a stable FQDN.
+
+### Steps
+
+1. **Create an App Service Plan** (skip if you have one):
+
+   ```bash
+   az appservice plan create \
+     --name minions-plan \
+     --resource-group rg-minions \
+     --sku B1 \
+     --is-linux
+   ```
+
+2. **Create the Web App:**
+
+   ```bash
+   az webapp create \
+     --name minions-dashboard \
+     --resource-group rg-minions \
+     --plan minions-plan \
+     --runtime "NODE:20-lts"
+   ```
+
+   This creates a publicly accessible URL: `https://minions-dashboard.azurewebsites.net`
+
+3. **Configure environment variables:**
+
+   ```bash
+   az webapp config appsettings set \
+     --name minions-dashboard \
+     --resource-group rg-minions \
+     --settings \
+       PORT=8080 \
+       NODE_ENV=production
+   ```
+
+   > Azure App Service routes external port 443 (HTTPS) to your app's internal port (default 8080). Set `PORT=8080` so the dashboard listens on the expected port.
+
+4. **Deploy the code:**
+
+   ```bash
+   # From the minions repository root
+   az webapp deploy \
+     --name minions-dashboard \
+     --resource-group rg-minions \
+     --src-path . \
+     --type zip
+   ```
+
+   Alternatively, configure continuous deployment from your Git repository:
+
+   ```bash
+   az webapp deployment source config \
+     --name minions-dashboard \
+     --resource-group rg-minions \
+     --repo-url https://github.com/your-org/minions \
+     --branch master \
+     --manual-integration
+   ```
+
+5. **Copy `config.json` to the App Service.** The simplest approach is to use the Kudu console or App Service Editor to upload your `config.json` to the application root. Alternatively, mount an Azure File Share containing your config.
+
+6. **Update the Azure Bot messaging endpoint:**
+
+   - Open the [Azure Portal](https://portal.azure.com) > your Azure Bot resource > **Configuration**.
+   - Change the **Messaging endpoint** to:
+     ```
+     https://minions-dashboard.azurewebsites.net/api/bot
+     ```
+   - Click **Apply**. The change takes effect immediately.
+
+### Verify
+
+1. Open `https://minions-dashboard.azurewebsites.net/api/routes` in a browser — you should see the API route list.
+2. In the Azure Bot resource, click **Test in Web Chat** and send a message.
+3. Send a message in Teams to the bot — confirm it receives and responds.
+
+### Rollback
+
+To revert to Dev Tunnel:
+
+1. Start your local Dev Tunnel: `devtunnel host -p 7331 --allow-anonymous`
+2. Update the Azure Bot messaging endpoint back to your tunnel URL: `https://<tunnel>.devtunnels.ms/api/bot`
+3. Click **Apply**. Traffic returns to your local machine immediately.
+
+---
+
+## Option 2: Azure Container App
+
+Containerize the dashboard and deploy to Azure Container Apps with a stable FQDN.
+
+### Steps
+
+1. **Create a Dockerfile** in the repository root:
+
+   ```dockerfile
+   FROM node:20-slim
+   WORKDIR /app
+   COPY package*.json ./
+   RUN npm ci --omit=dev 2>/dev/null || true
+   COPY . .
+   EXPOSE 7331
+   CMD ["node", "dashboard.js"]
+   ```
+
+   > Minions has zero npm dependencies beyond Node.js built-ins, so `npm ci` may be a no-op. The botbuilder package (added by this feature branch) is the exception.
+
+2. **Build and push to Azure Container Registry:**
+
+   ```bash
+   # Create a container registry (skip if you have one)
+   az acr create \
+     --name minionsacr \
+     --resource-group rg-minions \
+     --sku Basic
+
+   # Build and push
+   az acr build \
+     --registry minionsacr \
+     --image minions-dashboard:latest .
+   ```
+
+3. **Create a Container Apps environment** (skip if you have one):
+
+   ```bash
+   az containerapp env create \
+     --name minions-env \
+     --resource-group rg-minions \
+     --location eastus
+   ```
+
+4. **Deploy the container:**
+
+   ```bash
+   az containerapp create \
+     --name minions-dashboard \
+     --resource-group rg-minions \
+     --environment minions-env \
+     --image minionsacr.azurecr.io/minions-dashboard:latest \
+     --registry-server minionsacr.azurecr.io \
+     --target-port 7331 \
+     --ingress external \
+     --min-replicas 1 \
+     --max-replicas 1 \
+     --env-vars NODE_ENV=production
+   ```
+
+   > Use `--min-replicas 1 --max-replicas 1` because the Minions engine uses file-based state that doesn't support multiple replicas.
+
+5. **Get the FQDN:**
+
+   ```bash
+   az containerapp show \
+     --name minions-dashboard \
+     --resource-group rg-minions \
+     --query "properties.configuration.ingress.fqdn" \
+     --output tsv
+   ```
+
+   This returns something like: `minions-dashboard.happyfield-abc123.eastus.azurecontainerapps.io`
+
+6. **Update the Azure Bot messaging endpoint:**
+
+   - Open the [Azure Portal](https://portal.azure.com) > your Azure Bot resource > **Configuration**.
+   - Change the **Messaging endpoint** to:
+     ```
+     https://minions-dashboard.happyfield-abc123.eastus.azurecontainerapps.io/api/bot
+     ```
+   - Click **Apply**. The change takes effect immediately.
+
+### Verify
+
+1. Open `https://<your-fqdn>/api/routes` in a browser.
+2. Test via Azure Bot **Test in Web Chat**.
+3. Send a message in Teams — confirm end-to-end flow works.
+
+### Rollback
+
+To revert to Dev Tunnel:
+
+1. Start your local Dev Tunnel: `devtunnel host -p 7331 --allow-anonymous`
+2. Update the Azure Bot messaging endpoint back to your tunnel URL.
+3. Click **Apply**. Immediate switchover.
+
+Optionally stop the container to save costs:
+
+```bash
+az containerapp update \
+  --name minions-dashboard \
+  --resource-group rg-minions \
+  --min-replicas 0 --max-replicas 0
+```
+
+---
+
+## Option 3: Reverse Proxy (nginx / Caddy)
+
+For servers with a public IP address or an existing reverse proxy setup.
+
+### Steps (Caddy — recommended for simplicity)
+
+Caddy automatically provisions and renews TLS certificates via Let's Encrypt.
+
+1. **Install Caddy:**
+
+   ```bash
+   # Debian/Ubuntu
+   sudo apt install -y caddy
+
+   # macOS
+   brew install caddy
+   ```
+
+2. **Configure Caddy.** Create or edit `/etc/caddy/Caddyfile`:
+
+   ```
+   minions.yourdomain.com {
+     reverse_proxy localhost:7331
+   }
+   ```
+
+   > Replace `minions.yourdomain.com` with your actual domain. Ensure a DNS A record points this domain to your server's public IP.
+
+3. **Start Caddy:**
+
+   ```bash
+   sudo systemctl enable --now caddy
+   ```
+
+   Caddy automatically obtains a Let's Encrypt TLS certificate for your domain.
+
+4. **Start the Minions dashboard:**
+
+   ```bash
+   minions dash
+   ```
+
+   Or run it as a systemd service for persistence:
+
+   ```bash
+   # /etc/systemd/system/minions-dashboard.service
+   [Unit]
+   Description=Minions Dashboard
+   After=network.target
+
+   [Service]
+   Type=simple
+   User=your-user
+   WorkingDirectory=/path/to/minions
+   ExecStart=/usr/bin/node dashboard.js
+   Restart=on-failure
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+   ```bash
+   sudo systemctl enable --now minions-dashboard
+   ```
+
+5. **Update the Azure Bot messaging endpoint:**
+
+   - Open the Azure Portal > your Azure Bot resource > **Configuration**.
+   - Change the **Messaging endpoint** to:
+     ```
+     https://minions.yourdomain.com/api/bot
+     ```
+   - Click **Apply**. The change takes effect immediately.
+
+### Steps (nginx)
+
+1. **Install nginx and certbot:**
+
+   ```bash
+   sudo apt install -y nginx certbot python3-certbot-nginx
+   ```
+
+2. **Configure nginx.** Create `/etc/nginx/sites-available/minions`:
+
+   ```nginx
+   server {
+     listen 80;
+     server_name minions.yourdomain.com;
+
+     location / {
+       proxy_pass http://localhost:7331;
+       proxy_http_version 1.1;
+       proxy_set_header Upgrade $http_upgrade;
+       proxy_set_header Connection 'upgrade';
+       proxy_set_header Host $host;
+       proxy_set_header X-Real-IP $remote_addr;
+       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+       proxy_set_header X-Forwarded-Proto $scheme;
+     }
+   }
+   ```
+
+   ```bash
+   sudo ln -s /etc/nginx/sites-available/minions /etc/nginx/sites-enabled/
+   sudo nginx -t && sudo systemctl reload nginx
+   ```
+
+3. **Obtain a TLS certificate:**
+
+   ```bash
+   sudo certbot --nginx -d minions.yourdomain.com
+   ```
+
+   Certbot modifies the nginx config to add TLS and sets up auto-renewal.
+
+4. **Start the Minions dashboard** (same as Caddy option above).
+
+5. **Update the Azure Bot messaging endpoint** (same as Caddy option above).
+
+### Verify
+
+1. Open `https://minions.yourdomain.com/api/routes` in a browser — confirm the route list loads over HTTPS.
+2. Check the TLS certificate: `curl -vI https://minions.yourdomain.com 2>&1 | grep "SSL certificate"`.
+3. Test via Azure Bot **Test in Web Chat**.
+4. Send a message in Teams — confirm the bot responds.
+
+### Rollback
+
+To revert to Dev Tunnel:
+
+1. Start your local Dev Tunnel: `devtunnel host -p 7331 --allow-anonymous`
+2. Update the Azure Bot messaging endpoint back to your tunnel URL.
+3. Click **Apply**. Immediate switchover.
+
+The reverse proxy can remain running — it just won't receive Bot Framework traffic until the endpoint is pointed back.
+
+---
+
+## Choosing an Option
+
+| Criteria | App Service | Container App | Reverse Proxy |
+|----------|-------------|---------------|---------------|
+| Setup complexity | Medium | Medium | Low (Caddy) / Medium (nginx) |
+| TLS management | Automatic | Automatic | Automatic (Caddy/certbot) |
+| Cost | ~$13/mo (B1) | Pay-per-use | Free (your server + Let's Encrypt) |
+| Custom domain | Supported | Supported | Required |
+| Scaling | Supported but not needed | Supported but not needed | Manual |
+| Best for | Azure-native teams | Container workflows | Existing servers |
+
+> **Note on replicas:** Minions uses file-based state (`engine/*.json`). Do not run multiple replicas — use exactly 1 instance. All three options above default to single-instance deployment.
+
+## Common Notes
+
+- **Endpoint changes are immediate.** When you update the messaging endpoint in the Azure Bot Configuration, it takes effect right away. No bot reinstallation, no downtime, no user-visible change in Teams.
+- **No deprecated webhooks.** This guide uses Azure Bot Framework exclusively. Do not use deprecated O365 Connector webhooks or Power Automate flows — they are being removed by Microsoft.
+- **Config portability.** The same `config.json` works across all environments. Just ensure the `teams.appId` and `teams.appPassword` are correct for the bot registration that points to your production URL.