Update copilot-instructions.md with CLI, migration toolkit, and migration rules

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

Author: csharpfritz

.github/copilot-instructions.md

@@ -39,7 +39,7 @@ Both should render:
 ## Technology Stack
 
 - **.NET Version**: .NET 10.0 (see `global.json` for SDK version)
-- **Framework**: Blazor (Server-Side and WebAssembly)
+- **Framework**: Blazor (migration target is .NET 10 static SSR; samples also include Server-Side and WebAssembly)
 - **Project Type**: Razor Class Library (`Microsoft.NET.Sdk.Razor`)
 - **Testing Framework**: xUnit with bUnit for Blazor component testing
 - **Assertion Library**: Shouldly
@@ -51,14 +51,32 @@ Both should render:
 
 ```
 /docs                                 -- User documentation (MkDocs)
-/samples                              -- Usage samples
+/samples                              -- Usage samples and migration outputs
   BeforeWebForms/                     -- Original Web Forms sample (.NET Framework)
   AfterBlazorServerSide/              -- Blazor Server-Side samples
+  AfterBlazorServerSide.Tests/        -- Playwright tests for the sample app
   AfterBlazorClientSide/              -- Blazor WebAssembly samples
+  AfterContosoUniversity/             -- Migrated Contoso University sample
+  AfterDepartmentPortal/              -- Migrated department portal
+  AfterWingtipToys/                   -- Migrated WingtipToys sample
   SharedSampleObjects/                -- Shared models/data for samples
+  WingtipToys/                        -- Original WingtipToys Web Forms sample
+  ContosoUniversity/                  -- Original Contoso University Web Forms sample
+  DepartmentPortal/                   -- Original department portal
 /src
   BlazorWebFormsComponents/           -- Main component library
   BlazorWebFormsComponents.Test/      -- Unit tests with bUnit
+  BlazorWebFormsComponents.Analyzers/ -- Roslyn analyzers
+  BlazorWebFormsComponents.Analyzers.Test/ -- Analyzer tests
+  BlazorWebFormsComponents.Cli/       -- Web Forms to Blazor CLI pipeline and scaffolding
+  BlazorAjaxToolkitComponents/        -- AJAX Toolkit component library
+  WingtipToys.AcceptanceTests/        -- WingtipToys Playwright acceptance suite
+  ContosoUniversity.AcceptanceTests/  -- ContosoUniversity Playwright acceptance suite
+/tests
+  BlazorWebFormsComponents.Cli.Tests/ -- CLI transform and pipeline tests
+/migration-toolkit                    -- Wrapper scripts, skills, methodology, and benchmark helpers
+  scripts/                            -- bwfc-migrate.ps1, bwfc-scan.ps1, and compatibility wrappers
+  skills/                             -- bwfc-migration, bwfc-identity-migration, bwfc-data-migration, migration-standards, l3-performance-optimization
 ```
 
 ## Component Architecture
@@ -288,6 +306,17 @@ When testing component properties or state, use `FindComponent<T>()`:
 5. **No ViewState**: Store state in private fields or session (ViewState property exists but is syntax-only)
 6. **PostBack Compatibility**: `WebFormsPageBase` provides `IsPostBack`, `PostBack` event, and `__doPostBack()` JS interop bridge
 
+## Migration Rules
+
+These are hard rules for migration work in this repository:
+
+1. **Use the toolkit entry point**: Start project migrations with `migration-toolkit/scripts/bwfc-migrate.ps1` or the `webforms-to-blazor migrate` CLI it forwards to. Do not invent ad hoc regex converters or one-off migration scripts.
+2. **Always target Blazor static SSR**: Generated apps target .NET 10 static server-side rendering. Do not switch the whole app to interactive Blazor Server; only opt into interactive render modes deliberately and per page.
+3. **Trust the shims**: `WebFormsPageBase` preserves `Page.Request`, `Page.Response`, `Page.Session`, `Page.Server`, `Page.Cache`, `Page.ClientScript`, `IsPostBack`, and `ViewState`. Keep migrated code-behind compiling against those shims instead of rewriting to native ASP.NET Core services during Layer 1 or Layer 2 work.
+4. **Preserve BWFC data controls**: Never replace `ListView`, `FormView`, `GridView`, `DataList`, or `Repeater` with manual HTML tables or divs. Fix the generated BWFC markup, templates, item types, or child components instead.
+5. **Register transforms twice**: Every new CLI transform must be registered in both `src/BlazorWebFormsComponents.Cli/Program.cs` DI and `tests/BlazorWebFormsComponents.Cli.Tests/TestHelpers.cs` so the runtime pipeline and isolated test pipeline stay aligned.
+6. **Respect quarantine boundaries**: `PageQuarantineDetector` should quarantine non-essential `Account/`, `Admin/`, `Checkout/`, mobile, payment, or compile-surface blocker pages, but benchmark-critical home, about, contact, product, catalog, and cart flows stay on the runnable path whenever possible.
+
 ## Migration Shims
 
 The library provides compile-compatibility shims on `WebFormsPageBase` so migrated code-behind compiles unchanged:
@@ -314,6 +343,81 @@ When adding new components:
 4. Add sample page in `/samples/AfterBlazorServerSide/Pages/ControlSamples/`
 5. Document in `/docs/` folder (see Documentation Requirements below)
 
+## Migration CLI & Toolkit
+
+### Primary Entry Points
+
+- `src/BlazorWebFormsComponents.Cli/Program.cs` defines the `webforms-to-blazor` CLI entry point and command surface (`migrate`, `convert`, `prescan`, `scan`, `assets extract`, `edmx convert`).
+- `migration-toolkit/scripts/bwfc-migrate.ps1` is the supported migration-toolkit wrapper. It resolves the CLI project and forwards to `migrate` or `prescan` instead of maintaining a separate regex pipeline.
+- The migration-toolkit skill set currently includes `bwfc-migration`, `bwfc-identity-migration`, `bwfc-data-migration`, `migration-standards`, and `l3-performance-optimization`.
+
+### Pipeline Overview
+
+`MigrationPipeline` orchestrates the full migration sequence:
+
+1. `ProjectScaffolder` generates the .NET 10 Blazor static SSR scaffold unless `--skip-scaffold` is used.
+2. `WebConfigTransformer` converts `Web.config` settings into `appsettings.json`.
+3. Ordered markup transforms run first.
+4. Ordered code-behind transforms run second.
+5. `SemanticPatternCatalog` applies higher-level page rewrites.
+6. `PageQuarantineDetector` performs a late compile-surface pass and writes `migration-artifacts/quarantine-manifest.json` when pages must be stubbed.
+7. Static assets, source files, App_Start artifacts, NuGet assets, EDMX output, and redirect annotations are copied or generated.
+
+The CLI currently has **24 core markup transforms plus directive/infrastructure markup passes** and **27 code-behind transforms** wired through `Program.cs`.
+
+### Transform Registration Pattern
+
+When adding a transform:
+
+1. Create the transform class in `src/BlazorWebFormsComponents.Cli/Transforms/`.
+2. Register it in `BuildServiceProvider()` in `src/BlazorWebFormsComponents.Cli/Program.cs`.
+3. Add it to `CreateDefaultPipeline()` in `tests/BlazorWebFormsComponents.Cli.Tests/TestHelpers.cs`.
+4. Add or update focused transform tests and pipeline coverage.
+
+```csharp
+// Program.cs
+services.AddSingleton<IMarkupTransform, MyNewTransform>();
+
+// TestHelpers.cs
+var markupTransforms = new List<IMarkupTransform>
+{
+    new MyNewTransform(),
+};
+```
+
+### Scaffolding System
+
+- `RuntimeDetector` aggregates runtime signal detectors for Entity Framework, session, identity, and `Global.asax` usage.
+- `ProjectScaffolder` generates the project file, `_Imports.razor`, `Components/App.razor`, `Components/Routes.razor`, `Components/Layout/MainLayout.razor`, and launch settings.
+- `ProgramCsEmitter` generates `Program.cs` for .NET 10 static SSR, including `AddRazorComponents()`, `AddBlazorWebFormsComponents()`, `UseStaticFiles()`, and `UseAntiforgery()`.
+- `DatabaseProviderDetector` and `WebConfigTransformer` carry forward database provider and connection-string wiring.
+
+### Quarantine System
+
+- `PageQuarantineDetector` creates build-safe placeholder pages for compile-surface blockers and emits a manifest under `migration-artifacts/quarantine-manifest.json`.
+- Essential benchmark pages (home, about, contact, product, catalog, shopping cart, add-to-cart flows) are exempt from incidental quarantine signals.
+- Quarantined pages keep stub `.razor` and `.razor.cs` files plus the transformed original code-behind as an artifact for later Layer 2 or Layer 3 repair.
+
+### Acceptance Test Suites
+
+Use these suites as the migration quality gate for benchmark apps:
+
+```bash
+# WingtipToys migrated app
+# Set WINGTIPTOYS_BASE_URL first if the app is not on https://localhost:5001
+
+dotnet build src/WingtipToys.AcceptanceTests
+pwsh src/WingtipToys.AcceptanceTests/bin/Debug/net10.0/playwright.ps1 install chromium
+dotnet test src/WingtipToys.AcceptanceTests
+
+# ContosoUniversity benchmark/original app
+# Set CONTOSO_BASE_URL first if the app is not on http://localhost:44380
+
+dotnet build src/ContosoUniversity.AcceptanceTests
+pwsh src/ContosoUniversity.AcceptanceTests/bin/Debug/net10.0/playwright.ps1 install chromium
+dotnet test src/ContosoUniversity.AcceptanceTests
+```
+
 ## Documentation Requirements
 
 **IMPORTANT**: All features, fixes, and new components MUST include documentation updates.
@@ -372,10 +476,33 @@ dotnet build
 # Run tests
 dotnet test
 
+# Run CLI tests
+dotnet test tests/BlazorWebFormsComponents.Cli.Tests
+
+# Prescan a Web Forms app
+dotnet run --project src/BlazorWebFormsComponents.Cli -- prescan -i samples/WingtipToys
+
+# Run the migration CLI
+dotnet run --project src/BlazorWebFormsComponents.Cli -- migrate -i samples/WingtipToys -o samples/AfterWingtipToys
+
 # Run server-side samples
 dotnet run --project samples/AfterBlazorServerSide
 ```
 
+### Acceptance Test Commands
+
+```bash
+# WingtipToys migrated app (set WINGTIPTOYS_BASE_URL first if needed)
+dotnet build src/WingtipToys.AcceptanceTests
+pwsh src/WingtipToys.AcceptanceTests/bin/Debug/net10.0/playwright.ps1 install chromium
+dotnet test src/WingtipToys.AcceptanceTests
+
+# ContosoUniversity benchmark/original app (set CONTOSO_BASE_URL first if needed)
+dotnet build src/ContosoUniversity.AcceptanceTests
+pwsh src/ContosoUniversity.AcceptanceTests/bin/Debug/net10.0/playwright.ps1 install chromium
+dotnet test src/ContosoUniversity.AcceptanceTests
+```
+
 ## Key Interfaces
 
 - `IStyle` - Styling properties (BackColor, ForeColor, CssClass, etc.)
@@ -544,7 +671,9 @@ When making changes, ensure all related files are updated:
 | **Existing component modified** | Unit tests in `src/BlazorWebFormsComponents.Test/ComponentName/`, sample page if behavior changed, `docs/Category/ComponentName.md` if API changed |
 | **New migration shim added** | Shim class in `src/BlazorWebFormsComponents/`, register in `ServiceCollectionExtensions.cs` via `AddBlazorWebFormsComponents()`, update `docs/Migration/` guide, update `copilot-instructions.md` Migration Shims section |
 | **Base class changed** (`BaseWebFormsComponent`, `BaseStyledComponent`, `DataBoundComponent`) | Check all components inheriting from it — changes cascade to every component. Run full test suite. |
-| **CLI transform added** | Transform in `src/BlazorWebFormsComponents.Cli/`, test in `tests/BlazorWebFormsComponents.Cli.Tests/`, update `docs/cli/transforms.md`, update `docs/cli/index.md` transform count |
+| **CLI transform added** | Transform in `src/BlazorWebFormsComponents.Cli/Transforms/`, register it in `src/BlazorWebFormsComponents.Cli/Program.cs` and `tests/BlazorWebFormsComponents.Cli.Tests/TestHelpers.cs`, add or update transform tests, update `docs/cli/transforms.md`, update `docs/cli/index.md` transform count |
+| **CLI scaffolding/runtime changed** | Files in `src/BlazorWebFormsComponents.Cli/Scaffolding/` or `Pipeline/`, matching tests in `tests/BlazorWebFormsComponents.Cli.Tests/`, `migration-toolkit/README.md` or methodology docs if operator workflow changes, and `.github/copilot-instructions.md` if migration guidance changes |
+| **Migration toolkit wrapper or skill changed** | Matching files in `migration-toolkit/scripts/` or `migration-toolkit/skills/`, relevant `docs/Migration/` or `docs/cli/` pages, and `.github/copilot-instructions.md` when the recommended migration workflow changes |
 | **Analyzer rule added** | Rule in `src/BlazorWebFormsComponents.Analyzers/`, test in `src/BlazorWebFormsComponents.Analyzers.Test/`, update `docs/Analyzers/` |
 | **Target framework changed** | `Directory.Build.props` (version properties), all `.csproj` files (`TargetFrameworks`), `global.json`, `.github/workflows/build.yml` (dotnet-version), `.github/copilot-setup-steps.yml` |
 | **Documentation added/changed** | `docs/` markdown file, `mkdocs.yml` (`nav:` entry if new), verify local build passes with `docker run --rm -v "$(pwd):/docs" mkdocs build --strict` |

.squad/agents/bishop/history.md

@@ -37,6 +37,7 @@
 - NEVER replace ListView/FormView/GridView — must use BWFC components (2026-05-07T09:24)
 
 ## Learnings
+- **2026-05-08T10:00:31-04:00:** `copilot-instructions.md` now needs explicit migration-tooling guidance: start from the CLI wrapper, preserve BWFC data controls, trust `WebFormsPageBase` shims, and keep transform registration instructions paired across `Program.cs` and `TestHelpers.CreateDefaultPipeline()` so future agents can repair WingtipToys-class migrations without outside help.
 - **2026-05-07T13:17:32-04:00:** ListView `GroupTemplate` and `LayoutTemplate` emission is more reliable when the CLI emits explicit `Context` names (`items`, `groups`) instead of leaving raw `@context` placeholders. That keeps generated placeholder markup readable and removes one common manual repair step on Wingtip fixtures.
 - **2026-05-07T13:17:32-04:00:** Typed `GridView` columns must inherit the parent grid `ItemType`; leaving `TemplateField` at `ItemType="object"` breaks migrated template expressions like `@Item.Quantity`. A dedicated post-attribute-strip pass that rewrites child BWFC column generics to the grid row type fixes this deterministically.
 - **2026-05-07T13:58:11-04:00:** Compile-surface quarantine works best as a post-semantic pipeline decision, not just a code-behind transform. Letting semantic patterns normalize login/action pages first avoids quarantining pages the CLI can already turn into SSR-safe stubs.