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

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).

Issue	Title	Relationship
#1144	Squad telemetry from embedded host processes (Agent Framework wrappers)	#1565 telemetry section; update when #1144 resolves the forwarding mechanism
#1427	Enhancement: Create a /docs/security.md for corporate security	Sibling to #1567; both should eventually live under a `/security/` nav section
#1402	External State tracking: command and docs integration gaps	#1566 and #1568 reference state backend selection for containerized deployments
#1189	squad watch --execute --remote (ADC dispatch) RFC	Adjacent to #1566; #1566 documents the current supported path, #1189 is the future remote dispatch design
#1577	HTTP health/readiness contract for Squad services	Product gap discovered during docs validation of #1566/#1568 — not a docs child; engineering must define and ship the contract before ops docs can reference canonical health endpoints

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 ✅

🏷️ Issue type updated → type:epic

Child Issue Checklist

All five child issues have been filed. Updating umbrella with links:

docs: Squad.Agents.AI + Microsoft Agent Framework integration guide #1565 — docs: Squad.Agents.AI + Microsoft Agent Framework integration guide (P0, deliverable now)
docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566 — docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides (P0, deliverable now)
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 (P1, deliverable now)
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 (P1, deliverable now)
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) (P2, gated on platform stability + docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566)

Recommended sequence: #1565 and #1566 in parallel (P0) → #1567 and #1568 in parallel (P1) → #1569 (P2, after #1566 merges).

@tamirdresher

Hi @tamirdresher — this issue has been updated to serve as the decision-ready milestone roll-up for the real-world Squad docs wave, and your posts are the direct inspiration for the scope.

The wave covers five canonical docs areas:

Agent Framework integration (docs: Squad.Agents.AI + Microsoft Agent Framework integration guide #1565) — embedding Squad teams as MAF AIAgent instances in durable .NET workflows, with telemetry wiring and the GitHub.Copilot.SDK direct-reference workaround
Azure Container Apps / AKS hosting (docs: hosting Squad in Azure — Dockerfile, ACA, and AKS deployment guides #1566) — production Dockerfile, ACA and AKS deployment manifests, KEDA scaling
Production security hardening (docs: production security hardening — threat model, prompt injection defense, and credential hygiene #1567) — prompt injection defense via shared state, credential hygiene, supply chain, least-privilege token provisioning, external content trust tiers
Observability, state backend selection, and troubleshooting (docs: production operations — observability to Azure Monitor, state backend selection, and troubleshooting runbook #1568) — routing Squad telemetry to Azure Monitor, choosing state backends for containerized deployments, runbook
ACA Dynamic Sessions and Sandboxes (docs: aspirational — Squad tools in ACA Dynamic Sessions and Sandboxes (preview platform features) #1569) — preview/aspirational, gated on platform stability

Your published posts on tamirdresher.com were the primary source survey for all five areas. We've cited the original posts in each child issue body and will link to them as further reading in the finished pages.

We're not assigning any work to you — but if any of the above looks wrong, is missing a scenario you've documented, or the scope of a child issue doesn't match what you've observed in the field, we'd genuinely appreciate a note here before these pages ship. No obligation at all, just an open invitation.

Thank you for the detailed public writing that made this wave possible.

🏷️ Issue type updated → type:docs

🏷️ Issue type updated → type:epic