docs: align README, roadmap, framework wording, and AI prompt docs

README.md

@@ -2,13 +2,24 @@
 
 FastMoq is a provider-first .NET testing framework for auto-mocking, dependency-aware construction, and test-focused object creation. In v4, it ships with a bundled `reflection` default and optional Moq or NSubstitute integrations when you need provider-specific arrange syntax.
 
-## Start Here
+FastMoq is test-framework agnostic and can be used from xUnit, NUnit, MSTest, or other .NET test frameworks.
 
-- If you are evaluating the project for the first time, read `Why FastMoq` first, then `Packages`, then the documentation links below.
-- If you want the documentation portal home page with package-specific guidance, start with [FastMoq Documentation Home](https://help.fastmoq.com/).
+## Evaluate FastMoq
+
+If you are comparing FastMoq with direct mock-provider usage or deciding whether it fits your test stack, use this order:
+
+1. Read `Why FastMoq` below for the high-level value proposition.
+2. Use [Feature Comparison](https://help.fastmoq.com/docs/feature-parity/README.html) for the detailed FastMoq vs direct-provider story.
+3. Use [Provider Capabilities](https://help.fastmoq.com/docs/getting-started/provider-capabilities.html) when you need the exact provider boundary.
+4. Use [Benchmarks](https://help.fastmoq.com/docs/benchmarks/README.html) when you want the current measured runtime-overhead comparison.
+5. Use [Migration Guide](https://help.fastmoq.com/docs/migration/README.html) and [What's New Since 3.0.0](https://help.fastmoq.com/docs/whats-new/README.html) if you are coming from the `3.0.0` public line.
+6. Use [Roadmap Notes](https://help.fastmoq.com/docs/roadmap/README.html) only for future public product direction, not current support claims.
+
+## Choose Your Starting Point
+
+- If you already know you want package-specific guidance, start with [FastMoq Documentation Home](https://help.fastmoq.com/).
 - If you want a first test that works under the default `reflection` provider, start with [Getting Started Guide](https://help.fastmoq.com/docs/getting-started/README.html).
-- If you want tracked `.Setup(...)` syntax, read [Provider Selection Guide](https://help.fastmoq.com/docs/getting-started/provider-selection.html) before copying any Moq-fluent examples.
-- If you are upgrading from the `3.0.0` line, start with [Migration Guide](https://help.fastmoq.com/docs/migration/README.html) and [What's New Since 3.0.0](https://help.fastmoq.com/docs/whats-new/README.html).
+- If you want tracked provider-specific `.Setup(...)` syntax, read [Provider Selection Guide](https://help.fastmoq.com/docs/getting-started/provider-selection.html) before copying any Moq-fluent examples.
 - Front-door examples use a couple of different assertion styles. Match the assertion library your test project already uses and keep that style consistent within the project.
 - Authoring ladder for the current v4 line:
     1. provider-neutral helper first, such as `GetOrCreateMock(...)`, `Verify(...)`, `VerifyNoOtherCalls(...)`, `VerifyLogged(...)`, `WhenHttpRequest(...)`, or `AddType(...)`
@@ -38,10 +49,12 @@ FastMoq ships with a bundled `reflection` provider, so you can start without tak
 
 ### Works well when a suite needs to stay maintainable
 
-FastMoq pays off most when tests have multiple constructor dependencies, recurring framework abstractions, or a need to keep provider choices flexible over time. It targets .NET 8, 9, and 10, is designed around xUnit, and includes the analyzer pack by default in `FastMoq` and `FastMoq.Core` so provider-first guidance shows up directly in the IDE.
+FastMoq pays off most when tests have multiple constructor dependencies, recurring framework abstractions, or a need to keep provider choices flexible over time. It targets .NET 8, 9, and 10, works with the .NET test framework your suite already uses, and includes the analyzer pack by default in `FastMoq` and `FastMoq.Core` so provider-first guidance shows up directly in the IDE.
 
 ### FastMoq vs Direct Mock Provider Usage
 
+The example below uses xUnit-style attributes and Moq arrange syntax for illustration. The point of comparison is the FastMoq harness shape, not a requirement to use xUnit or Moq for every test suite.
+
 Using a mock provider directly:
 
 ```csharp

docfx.json

@@ -34,6 +34,7 @@
           "api/**.yml",
           "FAQs.md",
           "docs/README.md",
+          "docs/ai/**.md",
           "docs/api/**.md",
           "docs/benchmarks/**.md",
           "docs/breaking-changes/**.md",

docs/README.md

@@ -4,6 +4,8 @@ Welcome to the FastMoq documentation home page. Use this site when you already k
 
 If you are evaluating the project itself and want the high-level value proposition first, start with the [GitHub repository home page](https://github.com/cwinland/FastMoq).
 
+If you are coming from that repository overview and now want the usage-side guide set, use this page for package choices, testing guidance, migration detail, and capability-specific docs.
+
 ## Package Overview
 
 FastMoq ships as an aggregate package plus focused helper packages so a test suite can stay broad or stay lightweight depending on what it needs.
@@ -60,10 +62,19 @@ Perfect for developers new to FastMoq. Learn the basics and write your first tes
 - [Explicit constructor selection in tests](./getting-started/testing-guide.md#explicit-constructor-selection-in-tests)
 - [Web helper guidance for controller and request tests](./getting-started/testing-guide.md#controller-testing)
 - [Executable testing examples](./samples/testing-examples.md)
+- [AI prompt templates for new tests, modernization, and migration](./ai/README.md)
 - Understanding the architecture
 - Common patterns and best practices
 - Troubleshooting guide
 
+### 🤖 [AI-Assisted Workflows](./ai/README.md)
+
+Reusable prompt templates and guardrails for AI-assisted migration, new test authoring, and modernization work.
+
+- Task-specific prompts for migration, new tests, and modernization
+- Shared anti-hallucination rules for validating packages, providers, namespaces, and locally available APIs
+- Repo-first doc guidance for current-branch work with hosted-doc fallback guidance
+
 ### 🔄 [Migration Guide](./migration/README.md)
 
 Practical guidance for moving from the public `3.0.0` release toward the current `4.3.0` provider-first patterns.
@@ -86,10 +97,10 @@ Use the docs-side API overview when you want example-first entry points and cura
 
 Comprehensive comparison of FastMoq with other popular mocking frameworks.
 
-- Side-by-side feature comparison
-- Migration guides from Moq and NSubstitute
-- Links to runnable benchmarks when raw overhead comparisons matter
-- When to choose FastMoq vs alternatives
+- Grouped parity matrix across provider model, verification, setup, and framework-integration dimensions
+- Complete side-by-side examples only where the comparison materially helps the reader
+- Provider-dependent notes for scenarios that do not flatten cleanly into one portable abstraction
+- When to choose FastMoq versus a direct provider workflow
 
 ### 👨‍🍳 [Cookbook](./cookbook/README.md)
 
@@ -119,9 +130,13 @@ Runnable BenchmarkDotNet coverage for current provider-first FastMoq flows.
 - Includes the exact run command and benchmark scope for this branch
 - Links to the latest checked-in short-run results summary
 
-### 🗺️ [Roadmap Notes](./roadmap/README.md)
+### 🛣️ [Roadmap Notes](./roadmap/README.md)
+
+Forward-looking product direction for upcoming releases, including current v5 cleanup and generator planning.
 
-Current provider-first direction, active architectural work, and intentionally deferred items.
+- Near-term provider-first and helper-surface direction
+- v5 packaging and obsolete-surface cleanup
+- Formal [generator roadmap and design](./roadmap/generator-roadmap.md) for planned code-generation work
 
 ### 🆕 [What's New Since 3.0.0](./whats-new/README.md)
 
@@ -155,6 +170,7 @@ Intentional v4 breaking changes, with migration notes for changed behavior.
 Direct routes:
 
 - Provider-first authoring: [Getting Started](./getting-started/README.md), [Testing Guide](./getting-started/testing-guide.md), and [API quick reference](./api/quick-reference.md)
+- AI-assisted workflows: [AI Prompt Templates](./ai/README.md), [Testing Guide](./getting-started/testing-guide.md), and [Migration Guide](./migration/README.md)
 - Harness and wrapper decisions: [Choose The Narrowest Harness](./getting-started/testing-guide.md#choose-the-narrowest-harness) and [Local Wrapper Boundary](./getting-started/testing-guide.md#local-wrapper-boundary)
 - Migration cleanup: [Migration Guide](./migration/README.md), [Provider and compatibility guidance](./migration/provider-and-compatibility.md), and [API replacements and migration exceptions](./migration/api-replacements-and-exceptions.md)
 - Troubleshooting provider or package mismatches: [Provider selection](./getting-started/provider-selection.md), [Provider capabilities](./getting-started/provider-capabilities.md), and [Getting Started package choices](./getting-started/README.md#package-choices)