docs milestone: real-world Squad hosting, integrations, and operations #1564

Why This Milestone Exists

The Squad docs site has thorough, accurate coverage of local developer workflows. Real-world production patterns — embedding Squad in Microsoft Agent Framework (MAF) durable workflows, hosting in Azure container environments, hardening deployments from a security and operations standpoint, and leveraging ACA execution sandboxes — have lived primarily in community blog posts and first-party devblogs rather than the canonical docs site.

This means teams deploying Squad at Microsoft-scale must stitch together fragmented, unofficial guidance. This milestone closes that gap by producing a cohesive set of first-party docs pages covering end-to-end real-world Squad operations.

Reader Outcomes and Definition of Done

After this milestone ships, a developer with a working local Squad setup should be able to:

• Integrate a Squad team into a Microsoft Agent Framework durable .NET workflow with correct NuGet references, telemetry wiring, and workarounds for known SDK constraints.
• Deploy that integration to Azure Container Apps or AKS using a production-grade Dockerfile, Bicep/YAML manifests, and KEDA scaling configuration — with no dead ends.
• Harden the deployment against the production threat model: prompt injection via shared state, credential hygiene in AI-generated code, supply chain risks, least-privilege token provisioning, and external content trust tiers.
• Operate the deployment by routing Squad telemetry to Azure Monitor, choosing the right state backend for containerized workloads, and following a troubleshooting runbook when things go wrong.
• Understand the ACA Dynamic Sessions and Sandboxes execution model and what to watch for when those preview features stabilize.

Definition of done for each page:

• Accurate against current repo source code at merge time
• Runnable examples verified against a real deployment (not hypothetical)
• All links are first-party (docs.microsoft.com, learn.microsoft.com, this repo) or clearly labeled as external
• Production caveats and known limitations are explicit, not buried
• Cross-linking: each page links to related pages in this wave and to the relevant engineering issues
• Docs build and link checks pass in CI
• Review sign-off from the Squad member most relevant to that page's domain

Phased Checklist

Phase 0 — Foundations and Integration (P0)

• docs: Squad.Agents.AI + Microsoft Agent Framework integration guide #1565 — docs: Squad.Agents.AI + Microsoft Agent Framework integration guide ✅ merged
• docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566 — docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides ✅ merged

Phase 1 — Security and Operations (P1)

• docs: production security hardening — threat model, prompt injection defense, and credential hygiene #1567 — docs: production security hardening — threat model, prompt injection defense, and credential hygiene ✅ merged
• docs: production operations — observability to Azure Monitor, state backend selection, and troubleshooting runbook #1568 — docs: production operations — observability to Azure Monitor, state backend selection, and troubleshooting runbook ✅ merged

Phase 2 — Preview / Aspirational (P2, gated on platform stability)

• docs: aspirational — Squad tools in ACA Dynamic Sessions and Sandboxes (preview platform features) #1569 — docs: aspirational — Squad tools in ACA Dynamic Sessions and Sandboxes (preview platform features) ⏸️ PARKED — gated on ACA Dynamic Sessions / Sandboxes platform stability; will not merge until the preview API surface is stable enough to document without misleading readers

Infrastructure Dependency: #1314

#1314 — DX: .squad/ralph-instructions.md is an undocumented escape hatch in squad watch --execute — document it or remove it ✅ Resolved/closed — dependency no longer blocks any remaining wave work. #1569 (when it resumes) will reference the finalized behavior.

Companion Engineering Issues

These open engineering issues are not duplicates of this milestone — they are in-flight features or design threads whose resolution directly shapes what the docs pages can and should say. Each child issue above cross-links to its relevant companion(s).

Source and Inspiration

This backlog was identified through a systematic survey of Tamir Dresher's published content on tamirdresher.com, covering 10 posts from 2026-05-21 through 2026-07-30, cross-referenced against the current docs site and repo source. The survey was fact-checked against Squad source code and open issues. "Tamir's public posts informed the source survey; every proposed docs claim is independently checked against current Squad source and first-party documentation."

Specific posts that informed each child issue are cited in the individual child issue bodies. This section credits the source; it does not reproduce blog prose. All docs pages will link to the original posts as "further reading" where appropriate.

Progress and Success Criteria

Phase 0 + Phase 1 — Complete ✅

Content for #1565–#1568 has been written, reviewed, and merged via PRs #1574–#1580. First-party and Squad source review is complete for all four pages. Navigation structure is merged and live.

Phase 2 — Parked ⏸️

• docs: aspirational — Squad tools in ACA Dynamic Sessions and Sandboxes (preview platform features) #1569 unblocked when ACA Dynamic Sessions / Sandboxes API surface stabilizes
• Engineering companion feat: HTTP health/readiness endpoints for container deployments #1577 (HTTP health/readiness contract) resolved before ops docs finalize health endpoint guidance
• Engineering companions (Squad telemetry from embedded host processes (Agent Framework wrappers, no REPL): how should it reach Aspire? #1144, Enhancement: Create a /docs/security.md for corporate security #1427, [External State] Tracking: command and docs integration gaps #1402, [Cross-Squad] Design input: squad watch --execute --remote (ADC dispatch) #1189) reviewed for impact on page content at each future phase boundary
• Docs build and link-check CI passes with all new pages present (currently passing for merged pages)
• No broken cross-links between wave pages or to existing docs

This milestone remains open because #1569 is parked. It will close when #1569 merges or is explicitly abandoned by the team.

Sequence

Phase 0: #1565 (MAF integration) ✅
         #1566 (Azure hosting)   ✅
                                      Phase 1: #1567 (security) ✅ #1568 (ops) ✅
                                                                                    Phase 2: #1569 (preview) ⏸️ PARKED
                     #1314 resolved ✅