docs(bootcamp): split Unit 1 into parallel CLI + Embedded setup tracks

Unit 1 was the only unit with material shape-divergence (install +
wire-up). From Unit 2 on, the workbench UI is identical regardless of
how Bowire got mounted, so threading Path A/B inline through every
later lesson was duplication for nothing.

Now: Unit 0 ends by pointing at two parallel tracks --
units/unit-1-cli/ for the bowire --url two-process shape and
units/unit-1-embedded/ for the AddBowire()/MapBowire() in-process
shape. Each track is two lessons (first call + multi-protocol).
Learners walk one track, the other is a deliberate diff target.

Samples move to units/unit-1-samples/ so both tracks reference the
same HelloApi/HelloGrpc projects without duplication; the embedded
track instructs learners to add Kuestenlogik.Bowire and wire it up.

LEARNING_PATHS, units-overview, Unit 0 next-step, and the prereq
headers in Units 2-5 all updated to point at 'pick your track'
instead of the old monolithic Unit 1 link.

Author: thomas-stegemann

.docfx/docfx.json

@@ -5,8 +5,6 @@
                 "files": [
                     "units/**/README.md",
                     "units/**/INSTRUCTIONS.md",
-                    "units/**/cli.md",
-                    "units/**/embedded.md",
                     "units/**/toc.yml",
                     "capstone/**/README.md",
                     "capstone/**/REQUIREMENTS.md",
@@ -19,6 +17,9 @@
                     "toc.yml",
                     "index.md"
                 ],
+                "exclude": [
+                    "units/unit-1-samples/**"
+                ],
                 "src": ".."
             }
         ],

LEARNING_PATHS.md

@@ -1,10 +1,17 @@
 # Learning Paths
 
-Six role-based paths through the Bowire Bootcamp. Or, complete all units in order for the full picture (~3 hours).
+Five role-based paths through the Bowire Bootcamp. Or, complete all units in order for the full picture (~3 hours).
 
 Every path lists its **path-level prerequisites** (the toolchain you need before starting any of its units). Individual lessons also list their own prerequisites — those are subsets of the path-level list.
 
-> **First decision — pick your deployment shape.** Bowire ships in two: standalone **CLI** (point at any URL) and **embedded** (`AddBowire()` + `MapBowire()` in your own ASP.NET service). [Unit 0 → Lesson 0.1](units/unit-0/lesson-1/README.md) breaks the choice down with diagrams. Most paths below work with either shape; **Path #6 (Embedded Backend Workflow)** is the embedded-native walkthrough for backend devs mounting the workbench inside their service.
+> **First decision — pick your deployment shape.** Unit 0 introduces the two:
+>
+> - **CLI (two-process)** — `bowire --url <service>` from a terminal. Bowire is its own process; your service is untouched.
+> - **Embedded (single-process)** — `AddBowire()` + `MapBowire()` inside your ASP.NET host. Workbench mounts at `/bowire` on the host's own port.
+>
+> Unit 1 splits into two parallel **setup tracks** — [CLI](units/unit-1-cli/README.md) or [Embedded](units/unit-1-embedded/README.md). Pick one based on the shape that matches your deployment.
+>
+> From Unit 2 onwards the tracks merge — the workbench UI is identical regardless of how Bowire got mounted, so recording, mocking, AI integration, plugin authoring, and CI work are shared.
 
 ---
 
@@ -17,11 +24,12 @@ Every path lists its **path-level prerequisites** (the toolchain you need before
 **Prerequisites:**
 - [.NET 10 SDK](https://dotnet.microsoft.com/download) — for the sample REST + gRPC backends.
 - A modern web browser — workbench UI runs in-browser, opens automatically.
+- Either the `bowire` CLI installed (CLI track) **or** an ASP.NET host you can `dotnet add package Kuestenlogik.Bowire` into (Embedded track).
 
 | # | Unit | Why it matters |
 |---|------|----------------|
-| 1 | [Unit 0: Introduction](units/unit-0/README.md) | What Bowire is, how it positions vs Postman/Insomnia/Bruno, install verification |
-| 2 | [Unit 1: Workbench Basics](units/unit-1/README.md) | First REST call, multi-protocol session (REST + gRPC discovered side-by-side) |
+| 1 | [Unit 0: Introduction](units/unit-0/README.md) | What Bowire is, how it positions vs Postman/Insomnia/Bruno, install verification, **pick your setup track** |
+| 2 | Unit 1 — [CLI track](units/unit-1-cli/README.md) **or** [Embedded track](units/unit-1-embedded/README.md) | First REST call + multi-protocol session (REST + gRPC), walked through your chosen setup track |
 | 3 | [Unit 2.1: Record & Replay](units/unit-2/lesson-1/README.md) | Capture a session, save as `.bwr`, replay through `bowire mock` |
 
 ---
@@ -34,7 +42,7 @@ Every path lists its **path-level prerequisites** (the toolchain you need before
 
 **Prerequisites:**
 - [.NET 10 SDK](https://dotnet.microsoft.com/download) — the bootcamp's sample backend uses it; production frontend devs can swap in their own.
-- Bowire CLI: `dotnet tool install --global Kuestenlogik.Bowire.Tool`.
+- Bowire CLI: `dotnet tool install --global Kuestenlogik.Bowire.Tool`. (Mock-server is a CLI-only feature, so this path defaults to the CLI shape regardless of what your backend team uses.)
 
 | # | Unit | Why it matters |
 |---|------|----------------|
@@ -50,13 +58,13 @@ Every path lists its **path-level prerequisites** (the toolchain you need before
 **Units:** 2
 
 **Prerequisites:**
-- [.NET 10 SDK](https://dotnet.microsoft.com/download) + Bowire CLI.
+- [.NET 10 SDK](https://dotnet.microsoft.com/download) + Bowire CLI (or embedded host).
 - **Claude Desktop** or **Cursor** installed (any other MCP-aware host also works — the config snippet is portable).
 
 | # | Unit | Why it matters |
 |---|------|----------------|
-| 1 | [Unit 1: Workbench Basics](units/unit-1/README.md) | Understand Bowire's discovery + invoke surface first (the toolset the agent will drive) |
-| 2 | [Unit 3.1: AI-Agent Integration](units/unit-3/lesson-1/README.md) | `bowire mcp serve` over stdio, wire it into the agent's MCP config, drive REST + gRPC from a chat window |
+| 1 | Unit 1 — [CLI track](units/unit-1-cli/README.md) **or** [Embedded track](units/unit-1-embedded/README.md) | Understand Bowire's discovery + invoke surface first (the toolset the agent will drive) |
+| 2 | [Unit 3.1: AI-Agent Integration](units/unit-3/lesson-1/README.md) | `bowire mcp serve` over stdio (CLI shape), or `MapBowireMcpAdapter()` HTTP MCP (embedded shape) — wire it into the agent's MCP config, drive REST + gRPC from a chat window |
 
 ---
 
@@ -67,14 +75,14 @@ Every path lists its **path-level prerequisites** (the toolchain you need before
 **Units:** 3
 
 **Prerequisites:**
-- [.NET 10 SDK](https://dotnet.microsoft.com/download) + Bowire CLI.
+- [.NET 10 SDK](https://dotnet.microsoft.com/download) + Bowire CLI (or embedded host).
 - **Python 3.10+** + `pip` — only for the Unit 4.2 sidecar lesson. Unit 4.1 (.NET plugin) needs nothing beyond the SDK.
 - [`dotnet new bowire-plugin`](https://github.com/Kuestenlogik/Bowire.Templates) template installed: `dotnet new install Kuestenlogik.Bowire.Templates`.
 
 | # | Unit | Why it matters |
 |---|------|----------------|
-| 1 | [Unit 1: Workbench Basics](units/unit-1/README.md) | Understand how the host discovers and renders a protocol (REST + gRPC reference) |
-| 2 | [Unit 4.1: .NET Protocol Plugin](units/unit-4/lesson-1/README.md) | Implement `IBowireProtocol`, `dotnet pack`, `bowire plugin install` |
+| 1 | Unit 1 — [CLI track](units/unit-1-cli/README.md) **or** [Embedded track](units/unit-1-embedded/README.md) | Understand how the host discovers and renders a protocol (REST + gRPC reference) |
+| 2 | [Unit 4.1: .NET Protocol Plugin](units/unit-4/lesson-1/README.md) | Implement `IBowireProtocol`, `dotnet pack`, install via `bowire plugin install` (CLI) or `PackageReference` (Embedded) |
 | 3 | [Unit 4.2: Python Sidecar Plugin](units/unit-4/lesson-2/README.md) | Same surface, polyglot — `BowirePlugin` subclass, JSON-RPC stdio, ship as a zip |
 
 ---
@@ -86,7 +94,7 @@ Every path lists its **path-level prerequisites** (the toolchain you need before
 **Units:** 2
 
 **Prerequisites:**
-- [.NET 10 SDK](https://dotnet.microsoft.com/download) + Bowire CLI.
+- [.NET 10 SDK](https://dotnet.microsoft.com/download) + Bowire CLI. (CI workflows always run the CLI shape — there's no in-process host to mount the workbench into at CI time.)
 - **Docker** (for the CI examples that run the mock as a service container — optional in local dev).
 - A **GitHub repository** you can push the sample workflow to (any other CI runner works analogously; the lesson examples are GitHub Actions).
 
@@ -97,48 +105,18 @@ Every path lists its **path-level prerequisites** (the toolchain you need before
 
 ---
 
-## 6. Embedded Backend Workflow
-
-**For:** Backend developers and internal-tools teams who mount the workbench *inside* their own ASP.NET service via `AddBowire()` + `MapBowire()` — workbench inherits the host's DI container, `[Authorize]` policies, `IOptions<T>` config, and logging providers, so what the workbench discovers is exactly what production exposes.
-**Duration:** ~50 min
-**Units:** 3
-
-**Prerequisites:**
-- [.NET 10 SDK](https://dotnet.microsoft.com/download).
-- An ASP.NET host to mount Bowire into — either your own service, or scaffold a fresh one with `dotnet new web` (Lesson 0.2 walks the scaffold).
-- `Kuestenlogik.Bowire` NuGet referenced from the host (`dotnet add package Kuestenlogik.Bowire`). No separate `bowire` CLI install required for this path, though the CLI is handy to keep around for external targets.
-
-| # | Unit | Why it matters |
-|---|------|----------------|
-| 1 | [Unit 0: Introduction](units/unit-0/README.md) | Pick Path B in Lesson 0.2; mount the workbench in two lines |
-| 2 | [Unit 1: Workbench Basics](units/unit-1/README.md) | First call against your own in-process service — same workbench surface as the CLI path, no separate process |
-| 3 | [Unit 2.1: Record & Replay](units/unit-2/lesson-1/README.md) | Capture sessions against your own service; replay through `bowire mock` (CLI) for downstream consumers |
-
-**Where embedded beats CLI:**
-- The workbench inherits your auth pipeline. A method behind `[Authorize(Policy="…")]` needs the same token; no parallel credentials store.
-- Discovery reads gRPC reflection / OpenAPI document provider / SignalR hub registry directly through DI — faster, no schema-version drift.
-- Ship a debug UI *with* your binary — no separate distribution, no companion container.
-
-**Where CLI still beats embedded:**
-- External targets you don't control.
-- Air-gapped or CI environments where adding a NuGet to the host isn't an option.
-- MCP agents driving many services simultaneously — one CLI instance, many `--url` targets.
-
-> **Coverage status.** Unit 0 is the only one with full Path-A / Path-B coverage today. Other units still write samples for the CLI path by default; [Kuestenlogik/Bowire#55](https://github.com/Kuestenlogik/Bowire/issues/55) tracks bringing the embedded path to lesson-by-lesson parity. The embedded code path is fully supported in the product — the bootcamp just hasn't finished documenting every variant yet.
-
----
-
 ## Or: the full bootcamp
 
 Complete every unit in order — ~3 hours, ~9 lessons, plus the capstone.
 
 **Prerequisites (everything):**
 - [.NET 10 SDK](https://dotnet.microsoft.com/download)
-- Bowire CLI: `dotnet tool install --global Kuestenlogik.Bowire.Tool`
+- For the **CLI track of Unit 1** *and* Unit 5 (always CLI): Bowire CLI — `dotnet tool install --global Kuestenlogik.Bowire.Tool`
+- For the **Embedded track of Unit 1**: ASP.NET host (own, or scaffold via `dotnet new web`) + `dotnet add package Kuestenlogik.Bowire`
 - `dotnet new bowire-plugin` template: `dotnet new install Kuestenlogik.Bowire.Templates`
 - **Python 3.10+** (Unit 4.2 only)
 - **Claude Desktop** or **Cursor** (Unit 3.1 only)
 - **Docker** (Unit 5.1 only — optional in local dev)
 - A **GitHub repository** (Unit 5.1 only)
 
-- [Unit 0](units/unit-0/README.md) → [Unit 1](units/unit-1/README.md) → [Unit 2](units/unit-2/README.md) → [Unit 3](units/unit-3/README.md) → [Unit 4](units/unit-4/README.md) → [Unit 5](units/unit-5/README.md) → [Capstone](capstone/README.md)
+[Unit 0](units/unit-0/README.md) → Unit 1 ([CLI](units/unit-1-cli/README.md) or [Embedded](units/unit-1-embedded/README.md)) → [Unit 2](units/unit-2/README.md) → [Unit 3](units/unit-3/README.md) → [Unit 4](units/unit-4/README.md) → [Unit 5](units/unit-5/README.md) → [Capstone](capstone/README.md)

README.md

@@ -78,15 +78,24 @@ Understand what Bowire is and verify your environment.
 | [0.2](units/unit-0/lesson-2/README.md) | Setup | Install the bowire CLI, the bundled plugins, the workbench host |
 | [0.3](units/unit-0/lesson-3/README.md) | Hello Bowire | Launch the workbench, point it at a public REST API, invoke your first method |
 
-### Unit 1: Workbench Basics
-*Time: ~15 minutes*
+### Unit 1: Workbench Basics — pick your setup track
+*Time: ~15 minutes per track (you only walk one)*
+
+Drive Bowire's discovery and invoke surface across two protocols at once. Two parallel tracks based on your deployment shape — pick one and the rest of the bootcamp (Unit 2+) is shared.
+
+**[CLI track](units/unit-1-cli/README.md)** — for the `bowire --url <service>` two-process shape:
+
+| Lesson | Topic | What You'll Build |
+|--------|-------|-------------------|
+| [1.1](units/unit-1-cli/lesson-1/README.md) | First call (REST + OpenAPI) | A REST sample API, discovered through its OpenAPI doc, invoked from the workbench |
+| [1.2](units/unit-1-cli/lesson-2/README.md) | Multi-protocol session (REST + gRPC) | A gRPC sample side-by-side with REST via repeated `--url`, server-streaming demo |
 
-Drive Bowire's discovery and invoke surface across two protocols at once.
+**[Embedded track](units/unit-1-embedded/README.md)** — for the `AddBowire()` / `MapBowire()` in-process shape:
 
 | Lesson | Topic | What You'll Build |
 |--------|-------|-------------------|
-| [1.1](units/unit-1/lesson-1/README.md) | First call (REST + OpenAPI) | A REST sample API, discovered through its OpenAPI doc, invoked from the workbench |
-| [1.2](units/unit-1/lesson-2/README.md) | Multi-protocol session (REST + gRPC) | A gRPC sample side-by-side with REST, both discovered automatically, server-streaming demo |
+| [1.1](units/unit-1-embedded/lesson-1/README.md) | Mount the workbench in your host | `AddBowire()` + `MapBowire()` in `Program.cs`, workbench at `/bowire` on the host's port |
+| [1.2](units/unit-1-embedded/lesson-2/README.md) | Add a second protocol (gRPC) | gRPC co-hosted in the same ASP.NET process; the workbench picks both up through DI |
 
 ### Unit 2: Record, Replay, Mock
 *Time: ~20 minutes*

units-overview.md

@@ -5,7 +5,7 @@
 | Unit | Title | Lessons |
 |------|-------|---------|
 | [Unit 0](units/unit-0/README.md) | Introduction | 3 |
-| [Unit 1](units/unit-1/README.md) | Workbench Basics | 2 |
+| Unit 1 — pick one track: [CLI](units/unit-1-cli/README.md) or [Embedded](units/unit-1-embedded/README.md) | Workbench Basics — setup track for your deployment shape | 2 per track |
 
 ## Record, Replay, Mock (Unit 2)
 

units/unit-0/README.md

@@ -16,12 +16,15 @@ Understand what Bowire is, **pick your deployment shape** (standalone CLI vs emb
 |--------|-------|-------------------|
 | [0.1](lesson-1/README.md) | What is Bowire? | Multi-protocol API workbench, the **two-process** (CLI) and **single-process** (embedded) models, when to pick which |
 | [0.2](lesson-2/README.md) | Setup | Path A: install the `bowire` global tool. Path B: scaffold an ASP.NET host + `AddBowire()` / `MapBowire()`. Both paths covered side by side. |
-| [0.3](lesson-3/README.md) | Hello Bowire (CLI) | Launch the workbench against a public REST API, invoke your first method. Skipped on Path B — [Unit 1.1](../unit-1/lesson-1/README.md) is the embedded equivalent. |
+| [0.3](lesson-3/README.md) | Hello Bowire (CLI) | Launch the workbench against a public REST API, invoke your first method. Embedded learners can skim — Unit 1's [Embedded track](../unit-1-embedded/README.md) walks the in-process equivalent. |
 
 ## Why this unit
 
-Before you can drive Bowire across protocols, you need a working install and a clear mental model of what it is vs the API-client tools you've used before. The two deployment shapes (CLI vs Embedded) cover meaningfully different jobs, so Unit 0 makes the choice explicit before any code gets written. If you already know the positioning and have at least one path installed, skip straight to [Unit 1](../unit-1/README.md).
+Before you can drive Bowire across protocols, you need a working install and a clear mental model of what it is vs the API-client tools you've used before. The two deployment shapes (CLI vs Embedded) cover meaningfully different jobs, so Unit 0 makes the choice explicit before any code gets written. If you already know the positioning and have at least one path installed, head to Unit 1 — pick the [CLI track](../unit-1-cli/README.md) or the [Embedded track](../unit-1-embedded/README.md) based on your shape.
 
 ---
 
-**Next:** → [Unit 1: Workbench Basics](../unit-1/README.md)
+**Next:** Unit 1 — pick your setup track:
+
+- [CLI track](../unit-1-cli/README.md) — for the standalone `bowire --url` shape
+- [Embedded track](../unit-1-embedded/README.md) — for the `AddBowire()` / `MapBowire()` in-process shape

units/unit-0/lesson-2/README.md

@@ -158,7 +158,7 @@ If you want to add a plugin that isn't bundled, reference its NuGet next to `Kue
 | `bowire plugin list` errors with `Access denied` | A | Check `~/.bowire/plugins/` exists and is writable. The directory is created on first install; manual creation needs `mkdir -p`. |
 | Tool install times out behind a corporate proxy | A · B | Configure `dotnet nuget` proxy settings (`dotnet nuget config -s <feed>`) or set `HTTP_PROXY` / `HTTPS_PROXY`. |
 | `/bowire` returns 404 in the embedded host | B | Make sure `app.MapBowire()` runs **after** `var app = builder.Build()` but **before** `app.Run()`. ASP.NET ignores route registrations after `Run()` starts the host. |
-| Workbench renders but discovers no endpoints | B | The host has no services registered yet. Either add a sample route (`app.MapGet("/api/ping", () => "pong")`) or skip ahead to [Unit 1](../../unit-1/README.md) which adds a discovery target. |
+| Workbench renders but discovers no endpoints | B | The host has no services registered yet. Either add a sample route (`app.MapGet("/api/ping", () => "pong")`) or skip ahead to [Unit 1 — Embedded track](../../unit-1-embedded/README.md) which adds a discovery target. |
 
 ## Key Takeaways
 

units/unit-0/lesson-3/README.md

@@ -6,9 +6,9 @@
 
 Point your freshly-installed `bowire` at a public REST API, watch the workbench discover it, invoke one method. The smallest end-to-end loop that proves the install works — without writing any code or running any sample server yet.
 
-You'll bring your own sample API in [Unit 1.1](../../unit-1/lesson-1/README.md); this lesson uses one that's already on the public web.
+You'll bring your own sample API in [Unit 1 — CLI track Lesson 1.1](../../unit-1-cli/lesson-1/README.md); this lesson uses one that's already on the public web.
 
-> **Embedded users (Path B):** This lesson is CLI-native — pointing the workbench at a public URL is the CLI's day job. Skip ahead to [Unit 1.1](../../unit-1/lesson-1/README.md) which walks the equivalent loop against an in-process service. You can come back to this lesson later if you ever want to drive an external target.
+> **Embedded users:** This lesson is CLI-native — pointing the workbench at a public URL is the CLI's day job. Skip ahead to [Unit 1 — Embedded track Lesson 1.1](../../unit-1-embedded/lesson-1/README.md) which walks the equivalent loop against an in-process service. You can come back to this lesson later if you ever want to drive an external target.
 
 ## Steps
 
@@ -104,7 +104,10 @@ Petstore's REST endpoints are all unary. To see the streaming-pane shape, point
 
 You're done with Unit 0. Time to bring up your own sample API and drive REST + gRPC side-by-side in the same workbench.
 
-**Continue:** → [Unit 1: Workbench Basics](../../unit-1/README.md)
+**Continue:** Unit 1 — pick your setup track:
+
+- [CLI track](../../unit-1-cli/README.md)
+- [Embedded track](../../unit-1-embedded/README.md)
 
 ## Reference