refactor(Squad.Agents.AI): co-locate sample under src/ and consolidate README

- Moves the sample app from samples/squad-agents-ai-sample/ to
  src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ so it lives
  alongside the package it demonstrates.
- Folds the sample's standalone README into the package README, giving
  consumers one canonical doc for both the API and the runnable demo.
- Adds <Compile Remove="samples/**/*.cs" /> to Squad.Agents.AI.csproj
  so the library's wildcard glob does not pick up Program.cs in the
  co-located samples subdirectory.
- Updates the .csproj project reference, and CI workflow paths to match
  the new layout.
- Verified end-to-end: dotnet build, dotnet test (43/43 passing), and a
  sample sanity-check run (clear CLI-not-found error, no stack trace).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: tamirdresher

.github/workflows/squad-agents-ai-ci.yml

@@ -5,7 +5,7 @@ on:
     paths:
       - 'src/Squad.Agents.AI/**'
       - 'test/Squad.Agents.AI.Tests/**'
-      - 'samples/squad-agents-ai-sample/**'
+      - 'src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/**'
       - '.github/workflows/squad-agents-ai-ci.yml'
       - 'Directory.*.props'
       - 'Directory.*.json'
@@ -16,7 +16,7 @@ on:
     paths:
       - 'src/Squad.Agents.AI/**'
       - 'test/Squad.Agents.AI.Tests/**'
-      - 'samples/squad-agents-ai-sample/**'
+      - 'src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/**'
       - '.github/workflows/squad-agents-ai-ci.yml'
       - 'Directory.*.props'
       - 'Directory.*.json'
@@ -58,7 +58,7 @@ jobs:
         run: dotnet restore test/Squad.Agents.AI.Tests/Squad.Agents.AI.Tests.csproj -p:NuGetAudit=true
 
       - name: Restore sample
-        run: dotnet restore samples/squad-agents-ai-sample/Squad.Agents.AI.Sample.csproj -p:NuGetAudit=true
+        run: dotnet restore src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/Squad.Agents.AI.Sample.csproj -p:NuGetAudit=true
 
       - name: Build package
         run: dotnet build src/Squad.Agents.AI/Squad.Agents.AI.csproj --no-restore -c Release
@@ -67,7 +67,7 @@ jobs:
         run: dotnet build test/Squad.Agents.AI.Tests/Squad.Agents.AI.Tests.csproj --no-restore -c Release
 
       - name: Build sample
-        run: dotnet build samples/squad-agents-ai-sample/Squad.Agents.AI.Sample.csproj --no-restore -c Release
+        run: dotnet build src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/Squad.Agents.AI.Sample.csproj --no-restore -c Release
 
       - name: Test
         run: dotnet test test/Squad.Agents.AI.Tests/Squad.Agents.AI.Tests.csproj --no-build -c Release --logger trx --results-directory TestResults

samples/squad-agents-ai-sample/README.md

@@ -182,6 +182,79 @@ Parsed URI query keys: `teamRoot`, `cliPath`, `cwd`, `cliArgs` (semicolon-separa
 - `.nuspec` metadata with authors, tags, repository, and readme pointer
 - `LICENSE` copied from the repository root
 
+## Sample
+
+A runnable console application is included at
+`src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/`. It demonstrates the four
+core integration patterns in one place: basic DI, keyed DI with multiple agents,
+the `ConfigureCopilotClient` BYOK delegate, and streaming via `RunStreamingAsync`.
+
+### Prerequisites
+
+| Prerequisite | Notes |
+|---|---|
+| [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) | `dotnet --version` should print `10.x.x` |
+| GitHub Copilot CLI on `PATH` | Install from [github.com/github/copilot-cli](https://github.com/github/copilot-cli); verify with `copilot --version` |
+| Squad CLI installed | Follow the install guide in the [Squad repository README](https://github.com/tamirdresher/squad#readme) |
+| Initialized Squad team root | Run `squad init` in a directory; this becomes your team root |
+| GitHub Copilot authentication | Run `gh auth login` or `copilot auth login` once before running the sample |
+
+Set the team root path before running:
+
+```bash
+# Linux / macOS
+export SQUAD_TEAM_ROOT=/path/to/your/team-root
+
+# Windows PowerShell
+$env:SQUAD_TEAM_ROOT = "C:\path\to\your\team-root"
+```
+
+### Run
+
+Run all four flows in sequence:
+
+```bash
+dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/
+```
+
+Run a single flow (1–4):
+
+```bash
+dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=1
+dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=2
+dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=3
+dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=4
+```
+
+### Flow walkthrough
+
+**Flow 1 — Basic DI registration** — `AddSquadAgent` registers `SquadAgent` and the
+base `AIAgent` interface. Resolves the agent from DI, creates a session, calls
+`RunAsync`, and prints `AgentResponse.Text`.
+
+**Flow 2 — Keyed DI (multiple agents)** — `AddKeyedSquadAgent` registers two agents
+under keys `"alpha"` and `"beta"`. Resolution uses
+`GetRequiredKeyedService<SquadAgent>("alpha")`.
+
+**Flow 3 — BYOK / `ConfigureCopilotClient` delegate** — the delegate receives
+`CopilotClientOptions` after Squad has applied its defaults. Inject a custom token
+or environment variable. The routing gate prevents accidental redirection of
+`Cwd`, `CliPath`, or `CliArgs` — configure those on `SquadAgentOptions` directly.
+
+**Flow 4 — Streaming** — `RunStreamingAsync` returns
+`IAsyncEnumerable<AgentResponseUpdate>`. Each `update.Text` fragment is written to
+`Console.Write` without a newline for live token-by-token output.
+
+### Troubleshooting
+
+| Error | Cause | Fix |
+|---|---|---|
+| `GitHub Copilot CLI was not found on PATH` | `copilot` binary is missing or not on `PATH` | Install from [github.com/github/copilot-cli](https://github.com/github/copilot-cli); verify with `copilot --version` |
+| `Authentication failed` / `401` | Copilot CLI is not signed in | Run `gh auth login` or `copilot auth login` |
+| `SquadFolderPath does not exist` | `SQUAD_TEAM_ROOT` points to a non-existent path | Set `SQUAD_TEAM_ROOT` to an initialized Squad team directory |
+| `The system cannot find the file specified` (Win32Exception) | Copilot CLI not found | Same as first row above |
+| Build error: `Package Squad.Agents.AI not found` | Sample uses a project reference; ensure you run from the repo root | Run `dotnet build` from the repository root or pass `--project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/` |
+
 ## See also
 
 - Root repo: <https://github.com/bradygaster/squad>

src/Squad.Agents.AI/README.md

@@ -18,6 +18,9 @@
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <Version>0.1.0-preview</Version>
   </PropertyGroup>
+  <ItemGroup>
+    <Compile Remove="samples/**/*.cs" />
+  </ItemGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.Agents.AI.GitHub.Copilot" Version="1.7.0-preview.260526.1" />
     <PackageReference Include="Microsoft.Extensions.AI" Version="10.6.0" />

src/Squad.Agents.AI/Squad.Agents.AI.csproj

@@ -7,8 +7,8 @@
 //    Flow 3 — BYOK / ConfigureCopilotClient delegate
 //    Flow 4 — Streaming via RunStreamingAsync
 //
-//  Run: dotnet run --project samples/squad-agents-ai-sample/
-//  Run one flow: dotnet run --project samples/squad-agents-ai-sample/ -- --flow=1
+//  Run: dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/
+//  Run one flow: dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=1
 // ============================================================
 
 using Microsoft.Agents.AI;

samples/squad-agents-ai-sample/Program.cs …amples/Squad.Agents.AI.Sample/Program.cssamples/squad-agents-ai-sample/Program.cs renamed to src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/Program.cs samples/squad-agents-ai-sample/Program.cs renamed to src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/Program.cs

@@ -0,0 +1,3 @@
+# Squad.Agents.AI Sample
+
+For docs see [../../README.md#sample](../../README.md#sample).

src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/README.md

@@ -10,7 +10,7 @@
     <AllowUnsafeBlocks>false</AllowUnsafeBlocks>
   </PropertyGroup>
   <ItemGroup>
-    <ProjectReference Include="..\..\src\Squad.Agents.AI\Squad.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\Squad.Agents.AI.csproj" />
   </ItemGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.0" />