[tamirdresher]

Summary (Stack Layer 4 of 4 — splits #2239)

Consolidates the Squad 2.0 documentation into the published Astro Starlight site (squad-2-0-architecture.md, using-squad-across-clients.md, and reference pages) and aligns the specification suite.

Review fixes included in Layer 4

• Uses @bradygaster/squad-sdk/client as the canonical import path across all docs and samples (noting /clients only as a deprecated alias).
• Adds explicit Experimental Preview — Bring Your Own Server callouts on all durable-http / /backend sections clarifying that Squad ships only the contract, local backend, and outbound HTTP client, plus the opt-in --experimental-backend / SQUAD_EXPERIMENTAL_BACKEND=1 MCP flag.
• Updates all remaining 5-host references to all 7 supported hosts (copilot, claude, kiro, opencode, cursor, codex, antigravity) and reflects the Layer 1 projections (.codex/agents/squad.md + AGENTS.md pointer block, Kiro inclusion: manual, Cursor alwaysApply: false, Antigravity frontmatter MCP).
• Consolidates architectural documentation into the published Astro site and trims redundant prose in docs/SQUAD-2.0-OVERVIEW.md and docs/tutorials/*.md.

[github-actions]

🏗️ Architectural Review

Authoritative evidence: base-controlled pull_request_target reporter.

⚠️ Architectural review: 3 warning(s).

Severity	Category	Finding	Files
🟡 warning	bootstrap-area	5 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully.	packages/squad-cli/src/cli/core/backend-mcp.ts, packages/squad-cli/src/cli/core/clients.ts, packages/squad-cli/src/cli/core/command-help.ts, packages/squad-cli/src/cli/core/init.ts, packages/squad-cli/src/cli/core/upgrade.ts
🟡 warning	export-surface	Package entry point(s) modified with 238 new/changed export(s). New public API surface requires careful review for backward compatibility.	packages/squad-sdk/src/index.ts
🟡 warning	sweeping-refactor	This PR touches 63 files (63 modified/added, 0 deleted). Large PRs are harder to review — consider splitting if possible.	—

---

Automated architectural review — informational only.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit c7190a8

PR Scope: 🔧 Infrastructure

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with tamirdresher-microsoft-stack-3-experimental-backend
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	0 active Copilot thread(s) resolved (3 outdated skipped)
✅	CI passing	All checks passing

Files Changed (20 files, +1228 −21)

File	+/−
.changeset/squad-2-0-multi-host-clients.md	+14 −6
CONTRIBUTING.md	+11 −0
README.md	+13 −2
docs/SQUAD-2.0-OVERVIEW.md	+116 −0
docs/specification/client-backend-decoupling-v0.2.md	+9 −5
docs/specification/client-harness-adapters-v0.2.md	+5 −4
docs/src/content/docs/concepts/squad-2-0-architecture.md	+163 −0
docs/src/content/docs/get-started/migration.md	+17 −1
docs/src/content/docs/reference/cli.md	+6 −0
docs/src/content/docs/reference/config.md	+5 −0
docs/src/content/docs/reference/sdk.md	+20 −1
docs/src/content/docs/scenarios/client-compatibility.md	+2 −0
docs/src/content/docs/scenarios/upgrading.md	+60 −0
docs/src/content/docs/scenarios/using-squad-across-clients.md	+146 −0
docs/src/content/docs/whatsnew.md	+19 −1
docs/src/navigation.ts	+2 −0
docs/tutorials/durable-backend-and-custom-harness.md	+270 −0
docs/tutorials/multi-client-quickstart.md	+95 −0
test/docs-build.test.ts	+2 −1
test/squad-20-pack-smoke.test.ts	+253 −0

Total: +1228 −21

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟡 Impact Analysis — PR #2254

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	20
Files added	6
Files modified	14
Files deleted	0
Modules touched	3

🎯 Risk Factors

• 20 files changed (6-20 → MEDIUM)
• 3 modules touched (2-4 → MEDIUM)

📦 Modules Affected

docs (15 files)

• docs/SQUAD-2.0-OVERVIEW.md
• docs/specification/client-backend-decoupling-v0.2.md
• docs/specification/client-harness-adapters-v0.2.md
• docs/src/content/docs/concepts/squad-2-0-architecture.md
• docs/src/content/docs/get-started/migration.md
• docs/src/content/docs/reference/cli.md
• docs/src/content/docs/reference/config.md
• docs/src/content/docs/reference/sdk.md
• docs/src/content/docs/scenarios/client-compatibility.md
• docs/src/content/docs/scenarios/upgrading.md
• docs/src/content/docs/scenarios/using-squad-across-clients.md
• docs/src/content/docs/whatsnew.md
• docs/src/navigation.ts
• docs/tutorials/durable-backend-and-custom-harness.md
• docs/tutorials/multi-client-quickstart.md

root (3 files)

• .changeset/squad-2-0-multi-host-clients.md
• CONTRIBUTING.md
• README.md

tests (2 files)

• test/docs-build.test.ts
• test/squad-20-pack-smoke.test.ts

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

🟡 Changes recommended

Backend examples mishandle capability negotiation and approval identity, and reference guidance incorrectly implies automatic SDK environment configuration.

3 open issues

• Clarify SDK backend URL and token configuration · New
• Use backend-supported capability names · New
• Preserve approval turn identity across responses · New

What changed in this PR

Consolidates Squad 2.0 documentation into the published site, covering multi-host projections and the experimental backend contract.

Changes:

• Documents all seven hosts and the canonical /client import.
• Adds backend opt-in guidance, limitations, and tutorials.
• Updates navigation, documentation checks, specifications, and contributor guidance.

File	Description
test/​docs-build.test.ts	Checks the new documentation pages.
README.md	Introduces multi-host commands and guides.
docs/​tutorials/​multi-client-quickstart.md	Adds host setup and projection examples.
docs/​tutorials/​durable-backend-and-custom-harness.md	Adds backend and custom harness examples.
docs/​src/​navigation.ts	Links the new published guides.
docs/​src/​content/​docs/​scenarios/​using-squad-across-clients.md	Provides seven-host walkthroughs.
docs/​src/​content/​docs/​scenarios/​client-compatibility.md	Links multi-host guidance.
docs/​src/​content/​docs/​reference/​sdk.md	Documents client and backend APIs.
docs/​src/​content/​docs/​reference/​config.md	Describes client metadata and backend variables.
docs/​src/​content/​docs/​reference/​cli.md	Documents projection commands and experimental flags.
docs/​src/​content/​docs/​concepts/​squad-2-0-architecture.md	Explains architecture and conformance contracts.
docs/​SQUAD-2.0-OVERVIEW.md	Summarizes architecture and links canonical guides.
docs/​specification/​client-harness-adapters-v0.2.md	Aligns host projection requirements.
docs/​specification/​client-backend-decoupling-v0.2.md	Expands host and transport coverage.
CONTRIBUTING.md	Adds host-adapter contribution steps.

_{Review effort: Balanced}