docs(migration-toolkit): enforce shim-first migration strategy across all skills

Rewrote all 5 skills and 4 docs to prevent agents from manually
implementing session, redirect, and cookie logic when shims exist.

Key changes:
- Added MANDATORY RULES and ANTI-PATTERNS sections
- SessionShim is now THE primary session strategy (not Minimal API)
- Response.Redirect/Request.QueryString preserved via shims
- Added migration decision tree for common patterns
- Demoted shim-to-native conversion to optional L3 optimization
- Added DbContext materialization pattern for SelectMethod

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

Author: csharpfritz

migration-toolkit/CHECKLIST.md

@@ -40,7 +40,11 @@ The checklist is organized by the [three-layer pipeline](METHODOLOGY.md). Work t
 - [ ] Event handlers converted to Blazor signatures (remove `sender`, `EventArgs`)
 - [ ] ✅ `Page_Load` / `IsPostBack` — works AS-IS via `WebFormsPageBase` (only signature `Page_Load(sender, e)` → `OnInitializedAsync` needs converting; `IsPostBack` inside works unchanged)
 - [ ] ✅ `Response.Redirect` — works AS-IS via ResponseShim (auto-strips `~/` and `.aspx`)
-- [ ] ✅ `Session["key"]` — works AS-IS via SessionShim (no longer needs Layer 3)
+- [ ] Session state: Use `Session["key"]` from `WebFormsPageBase` (SessionShim) — works in interactive mode ✅
+- [ ] ✅ Response.Redirect() calls work via ResponseShim
+- [ ] ✅ Request.QueryString[] calls work via RequestShim
+- [ ] No raw `IHttpContextAccessor` injected (use shim properties from `WebFormsPageBase` instead)
+- [ ] No Minimal API endpoints created for page actions (use shim methods instead; minimal APIs are ONLY for cookie auth operations)
 - [ ] ✅ `Page.Title` / `Page.MetaDescription` — works AS-IS via WebFormsPageBase
 - [ ] ✅ `Request.QueryString["key"]` — works AS-IS via RequestShim
 - [ ] ✅ `Cache["key"]` — works AS-IS via CacheShim
@@ -54,7 +58,9 @@ The checklist is organized by the [three-layer pipeline](METHODOLOGY.md). Work t
 
 - [ ] Data access pattern decided (injected service, EF Core, Dapper, etc.)
 - [ ] Data service implemented and registered in `Program.cs`
-- [ ] Session state: basic usage works AS-IS via SessionShim; if persistent/distributed state needed, replace with `ProtectedSessionStorage` or scoped service
+- [ ] Session state: basic usage works AS-IS via SessionShim; if persistent/distributed state needed, replace with `ProtectedSessionStorage` or scoped service (OPTIONAL — shim works correctly)
+- [ ] Response.Redirect: works AS-IS via ResponseShim; if removing BWFC dependency, replace with `NavigationManager.NavigateTo()` (OPTIONAL — shim works correctly)
+- [ ] Request.QueryString: works AS-IS via RequestShim; if cleaner Blazor pattern desired, replace with `[SupplyParameterFromQuery]` (OPTIONAL — shim works correctly)
 - [ ] Authentication/authorization wired (if page requires auth)
 - [ ] Third-party integrations ported (API calls, payment, etc.)
 - [ ] Route registered and tested (`@page` directive matches expected URL)

migration-toolkit/METHODOLOGY.md

@@ -74,7 +74,9 @@ Layer 1 handles every transform that can be applied mechanically. The CLI tool a
 | File renaming (`.aspx` → `.razor`) | 33 | 100% |
 | Project scaffold (`.csproj`, `Program.cs`, `_Imports.razor`, `App.razor`) | Full | ✅ |
 
-`_Imports.razor` includes `@inherits BlazorWebFormsComponents.WebFormsPageBase` so that all converted pages get `Page.Title`, `Page.MetaDescription`, `Page.MetaKeywords`, and `IsPostBack` without per-page injection. The layout scaffold includes `<BlazorWebFormsComponents.Page />` to render `<PageTitle>` and `<meta>` tags.
+The CLI generates `_Imports.razor` with `@inherits BlazorWebFormsComponents.WebFormsPageBase` so every page automatically gets `Page.Title`, `Page.MetaDescription`, `Page.MetaKeywords`, `IsPostBack`, `Session`, `Response`, `Request`, `Server`, `Cache`, and `ClientScript` — with the same API as Web Forms. The layout scaffold includes `<BlazorWebFormsComponents.Page />` to render `<PageTitle>` and `<meta>` tags.
+
+The CLI also generates `Program.cs` with `builder.Services.AddBlazorWebFormsComponents()`, which registers all the shim infrastructure (SessionShim, ResponseShim, RequestShim, CacheShim, ServerShim, ClientScriptShim, ViewStateShim) automatically.
 
 ### Shim Infrastructure
 
@@ -126,6 +128,10 @@ After Layer 1, pages fall into three readiness categories:
 
 Layer 2 handles transforms that follow consistent patterns but require understanding control semantics. A human *could* do these mechanically, but it's tedious and error-prone. Copilot with the BWFC migration skill handles them reliably.
 
+**L2 Principle: Wire up data binding and lifecycle — NOT to replace shims with native patterns.**
+
+The shims ARE the L2 strategy. If the original Web Forms code says `Session["CartId"]`, the migrated code says `Session["CartId"]`. The shim makes this work. Don't reinvent what already exists. Layer 2 is about making data flow through the page and connecting event handlers — NOT about converting `Response.Redirect()` to `NavigationManager.NavigateTo()`. That's an optional Layer 3 optimization.
+
 ### What Shims Handle Automatically (no Layer 2 work needed)
 
 These items were previously Layer 2 manual transforms but are now handled AS-IS by BWFC shims:
@@ -183,9 +189,9 @@ Always review Copilot's changes before committing.
 > | Approach | When to Use | Example |
 > |---|---|---|
 > | **Shim path** (keep AS-IS) | Migration speed is the priority; code works correctly; team isn't ready to learn Blazor-native patterns yet | `Response.Redirect("~/Products")` — works via ResponseShim |
-> | **Native Blazor path** (refactor later) | Post-migration polish; team is comfortable with Blazor; want to reduce BWFC dependency | `NavigationManager.NavigateTo("/Products")` — native Blazor |
+> | **Native Blazor path** (refactor later) | **Layer 3 optimization** — post-migration polish; team is comfortable with Blazor; want to reduce BWFC dependency | `NavigationManager.NavigateTo("/Products")` — native Blazor |
 >
-> **Recommendation:** Use shims to get migrated fast, then refactor to native Blazor incrementally as your team builds Blazor expertise. Both paths produce working code.
+> **Recommendation:** Use shims to get migrated fast (Layer 2), then refactor to native Blazor incrementally in Layer 3 as your team builds Blazor expertise. Both paths produce working code. **Replacing shims with native patterns is OPTIONAL, not required.**
 
 ---
 
@@ -196,6 +202,8 @@ Always review Copilot's changes before committing.
 
 Layer 3 is the ~15% of migration work that requires understanding your application's architecture. No script or AI can make these decisions for you — but the data migration skill and Copilot can guide you through the options and trade-offs.
 
+**Important:** Replacing shims with native Blazor patterns (e.g., `Response.Redirect()` → `NavigationManager.NavigateTo()`) is an **OPTIONAL Layer 3 optimization**, not a migration requirement. Your app works with the shims. Native patterns are for teams that want to reduce BWFC dependency long-term.
+
 ### Common Layer 3 Decisions
 
 | Decision | Web Forms Pattern | Blazor Options |

migration-toolkit/QUICKSTART.md

@@ -102,14 +102,33 @@ After the migration script runs, verify these are in place (the script scaffolds
 @inherits BlazorWebFormsComponents.WebFormsPageBase
 ```
 
-The `@inherits` line makes every page inherit from `WebFormsPageBase`, which provides `Page.Title`, `Page.MetaDescription`, `Page.MetaKeywords`, and `IsPostBack` — so Web Forms code-behind compiles unchanged.
+**This one line gives every page the Web Forms API:**
+- `Page.Title`, `Page.MetaDescription`, `Page.MetaKeywords`
+- `IsPostBack` (false on first render, true on interactions)
+- `Session["key"]` (scoped in-memory dictionary)
+- `Response.Redirect("~/path")` (auto-strips `~/` and `.aspx`)
+- `Request.Url`, `Request.QueryString["key"]`, `Request.Form["key"]`
+- `Cache["key"]` (application-level cache)
+- `Server.MapPath("~/path")` (virtual → physical path)
+- `ClientScript.RegisterStartupScript(...)` (JS interop)
+
+Your Web Forms code-behind compiles **unchanged**. No manual conversion needed.
 
 **`Program.cs`** — register BWFC services:
 ```csharp
 builder.Services.AddBlazorWebFormsComponents();
 ```
 
-> **This single call registers ALL shims automatically.** After this, `Response.Redirect`, `Session["key"]`, `Request.QueryString`, `Cache["key"]`, `Server.MapPath`, `ClientScript`, and `ViewState` all work AS-IS in your migrated code-behind files — no manual conversion needed.
+**What this does:**
+- Registers `SessionShim` (scoped in-memory dictionary for `Session["key"]`)
+- Registers `ResponseShim` (handles `Response.Redirect`, `Response.Write`)
+- Registers `RequestShim` (provides `Request.QueryString`, `Request.Form`, `Request.Url`)
+- Registers `CacheShim` (in-memory application cache)
+- Registers `ServerShim` (provides `Server.MapPath`)
+- Registers `ClientScriptShim` (JS interop for `ClientScript.RegisterStartupScript`)
+- Registers `ViewStateShim` (compile-compatible dictionary)
+
+After this single call, all Web Forms APIs work AS-IS in your migrated code — no manual conversion required.
 
 **Layout (`MainLayout.razor`)** — add the Page render component:
 ```razor
@@ -166,6 +185,50 @@ The following are **no longer Layer 2 work** — they work AS-IS via shims:
 - ~~`Session["key"]` → mark for Layer 3~~ → works via SessionShim
 - ~~`Page.Title` conversion~~ → works via WebFormsPageBase
 
+### Using Shims (No Conversion Needed)
+
+**The shims preserve Web Forms API calls AS-IS.** Here's what works unchanged:
+
+```csharp
+// Session access — works exactly like Web Forms
+Session["CartId"] = cartId;
+var cartId = Session["CartId"];
+
+// Response.Redirect — auto-strips ~/ and .aspx
+Response.Redirect("~/Products");
+Response.Redirect("~/Product.aspx?id=5"); // becomes /Product/5 if routing configured
+
+// Request.QueryString — reads URL parameters
+var productId = Request.QueryString["id"];
+
+// Request.Form — reads form POST data (requires <WebFormsForm> wrapper)
+var username = Request.Form["username"];
+
+// IsPostBack — false on first render, true on interactions
+if (!IsPostBack)
+{
+    LoadInitialData();
+}
+
+// Page properties — auto-rendered by <Page /> component
+Page.Title = "Product Details";
+Page.MetaDescription = "View product details";
+
+// Cache — application-level cache
+Cache["RecentProducts"] = products;
+
+// Server.MapPath — virtual to physical path
+var filePath = Server.MapPath("~/App_Data/config.xml");
+```
+
+**Do NOT inject these services manually:**
+- ❌ `IHttpContextAccessor` — use `Request` property instead
+- ❌ `NavigationManager` (for redirects) — use `Response.Redirect()` instead
+- ❌ `IMemoryCache` — use `Cache` property instead
+- ❌ `IJSRuntime` (for startup scripts) — use `ClientScript.RegisterStartupScript()` instead
+
+The shim properties are already available via `WebFormsPageBase`. Injecting these services and manually converting is extra work that provides no migration benefit.
+
 Look for `<!-- TODO: BWFC-MIGRATE -->` comments left by the migration script — these mark items that need manual attention.
 
 ---
@@ -175,14 +238,59 @@ Look for `<!-- TODO: BWFC-MIGRATE -->` comments left by the migration script —
 These are the decisions that need a human (or a human + the migration agent):
 
 - **Data access:** Replace `SqlDataSource`/`ObjectDataSource` with injected services
-- **Session state:** Convert `Session["key"]` to scoped services or `ProtectedSessionStorage` (if you need persistence — basic usage works AS-IS via SessionShim)
+- **Session state:** Convert `Session["key"]` to scoped services or `ProtectedSessionStorage` (if you need persistence or distributed sessions — basic usage works AS-IS via SessionShim)
 - **Authentication:** Migrate ASP.NET Membership/Identity to ASP.NET Core Identity
 - **EF6 → EF Core:** Update DbContext, register with DI, adjust LINQ queries
 - **Global.asax → Program.cs:** Convert lifecycle hooks to middleware
 - **Third-party integrations:** Port to `HttpClient` pattern
+- **Shim replacement (OPTIONAL):** Replace `Response.Redirect()` with `NavigationManager.NavigateTo()`, `Session` with injected state services, etc. — this is a performance/modernization step, NOT a migration requirement
 
 > 📄 For interactive guidance, use the [Data Migration Skill](skills/bwfc-data-migration/SKILL.md)
 
+### Common Mistakes to Avoid
+
+**Anti-pattern #1: Manually converting shim-supported APIs**
+
+❌ **Wrong:**
+```csharp
+@inject NavigationManager Nav
+@code {
+    void GoToProducts() => Nav.NavigateTo("/Products");
+}
+```
+
+✅ **Correct (use the shim):**
+```csharp
+@code {
+    void GoToProducts() => Response.Redirect("~/Products");
+}
+```
+
+**Anti-pattern #2: Injecting services that shims already provide**
+
+❌ **Wrong:**
+```csharp
+@inject IHttpContextAccessor HttpContext
+@code {
+    var id = HttpContext.HttpContext.Request.Query["id"];
+}
+```
+
+✅ **Correct (use the shim):**
+```csharp
+@code {
+    var id = Request.QueryString["id"];
+}
+```
+
+**Anti-pattern #3: Treating shims as temporary scaffolding**
+
+❌ **Wrong mindset:** "I'll use shims to get it compiling, then replace them with 'real' Blazor code."
+
+✅ **Correct mindset:** "Shims are the migration strategy. They work correctly. Replacing them is an optional optimization I can do later if my team wants to reduce BWFC dependency."
+
+The shims ARE the solution, not a workaround.
+
 ---
 
 ## Step 8: Build and Verify

migration-toolkit/README.md

@@ -27,6 +27,22 @@ You're a .NET developer who owns a Web Forms application and wants to migrate it
 
 ---
 
+## Key Principle: Shim-First Migration
+
+**The goal is to preserve the original Web Forms API calls, not rewrite them.**
+
+When you migrate with BWFC:
+
+- Pages inherit from `WebFormsPageBase`, which provides `Session`, `Response`, `Request`, `Server`, `Cache`, and `ClientScript` — **all with the SAME API as Web Forms**
+- Your code-behind continues to use `Response.Redirect("~/Products")`, `Session["CartId"]`, `Request.QueryString["key"]`, and `IsPostBack` — no changes needed
+- `AddBlazorWebFormsComponents()` in `Program.cs` registers all the shim infrastructure automatically
+
+**This means:** If the original Web Forms code says `Session["CartId"]`, the migrated code says `Session["CartId"]`. The shim makes it work. You are not converting to `IMemoryCache`, `NavigationManager`, or `IHttpContextAccessor` — those are native Blazor patterns that you can adopt *later* if desired, but they are not required for migration.
+
+Shims get your app compiling and running **fast**. Refactoring to native Blazor patterns is an optional Layer 3 optimization, not a migration requirement.
+
+---
+
 ## How to Use This Toolkit
 
 1. **Copy the `skills/` folder** into your project's `.github/skills/` directory.
@@ -65,10 +81,10 @@ Migration isn't one step — it's three layers that handle different kinds of wo
 
 | Layer | What | How | Coverage |
 |---|---|---|---|
-| **Layer 1** — Automated | Tag prefix removal, `runat` removal, expression conversion, file renaming, shim infrastructure | [`webforms-to-blazor` CLI](../src/BlazorWebFormsComponents.Cli/) or [`bwfc-migrate.ps1`](scripts/bwfc-migrate.ps1) + `AddBlazorWebFormsComponents()` | ~60% of work |
-| **Layer 2** — Copilot-Assisted | Data binding rewiring, layout conversion, lifecycle method signatures, event handlers | [`skills/bwfc-migration/SKILL.md`](skills/bwfc-migration/SKILL.md) | ~30% of work |
+| **Layer 1** — Automated | Tag prefix removal, `runat` removal, expression conversion, file renaming, **shim infrastructure setup** (`_Imports.razor` with `@inherits WebFormsPageBase`, `Program.cs` with `AddBlazorWebFormsComponents()`) | [`webforms-to-blazor` CLI](../src/BlazorWebFormsComponents.Cli/) or [`bwfc-migrate.ps1`](scripts/bwfc-migrate.ps1) | ~60% of work |
+| **Layer 2** — Copilot-Assisted | Data binding rewiring, layout conversion, lifecycle method signatures, event handlers — **uses shims to preserve Web Forms patterns** (`Response.Redirect`, `Session`, `Request`, `IsPostBack` all work AS-IS) | [`skills/bwfc-migration/SKILL.md`](skills/bwfc-migration/SKILL.md) | ~30% of work |
 | **Layer 3** — Architecture Decisions | Identity, EF Core, third-party integrations | [`skills/bwfc-data-migration/SKILL.md`](skills/bwfc-data-migration/SKILL.md) + human judgment | ~10% of work |
-| **L3-opt** — Performance (optional) | Async/await, `AsNoTracking`, `IDbContextFactory`, .NET 10 patterns | [`skills/l3-performance-optimization/SKILL.md`](skills/l3-performance-optimization/SKILL.md) | After app is functional |
+| **L3-opt** — Performance (optional) | Async/await, `AsNoTracking`, `IDbContextFactory`, .NET 10 patterns, **optionally replacing shims with native Blazor patterns** | [`skills/l3-performance-optimization/SKILL.md`](skills/l3-performance-optimization/SKILL.md) | After app is functional |
 
 **Start here:** [QUICKSTART.md](QUICKSTART.md) — the linear "just tell me what to do" path.