docs: Fix installation commands and resolve broken documentation links

CLAUDE.md

@@ -15,11 +15,12 @@ dotnet restore
 # Build the entire solution
 dotnet build
 
-# Run all tests
-dotnet test
+# Run all tests (requires framework specification for MTP)
+dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0
 
-# Run tests with detailed output
-dotnet test --logger "console;verbosity=detailed"
+# Run tests on specific framework
+dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net9.0
+dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net10.0
 
 # Build in release mode
 dotnet build -c Release
@@ -28,6 +29,8 @@ dotnet build -c Release
 dotnet clean
 ```
 
+**Note**: The test project uses Microsoft Testing Platform (MTP) and targets multiple frameworks (net8.0, net9.0, net10.0), so you must specify the `--framework` flag when running tests.
+
 ## Project Structure
 
 The solution contains four main projects:

README.md

@@ -25,7 +25,7 @@ DecoWeaver is a .NET incremental source generator that brings **compile-time dec
 Install the NuGet package:
 
 ```bash
-dotnet add package DecoWeaver
+dotnet add package DecoWeaver --prerelease
 ```
 
 Ensure your project uses C# 11 or later:
@@ -96,7 +96,6 @@ Key sections:
 - [Core Concepts](https://layeredcraft.github.io/decoweaver/core-concepts/how-it-works/) - Understand how it works
 - [Usage Guide](https://layeredcraft.github.io/decoweaver/usage/class-level-decorators/) - Detailed usage patterns
 - [Examples](https://layeredcraft.github.io/decoweaver/examples/) - Real-world scenarios
-- [Troubleshooting](https://layeredcraft.github.io/decoweaver/advanced/troubleshooting/) - Common issues and solutions
 
 ## Contributing
 

docs/advanced/keyed-services.md

@@ -0,0 +1,30 @@
+# Keyed Services Strategy
+
+!!! info "Coming Soon"
+    This documentation is under development. Check back soon for detailed information about how DecoWeaver uses keyed services internally.
+
+## Overview
+
+This page will cover:
+
+- How DecoWeaver uses .NET 8.0+ keyed services to prevent circular dependencies
+- The internal keying strategy for undecorated implementations
+- Why keyed services are necessary for decorator chains
+- Performance implications
+
+## Planned Content
+
+- [ ] Keyed services architecture explanation
+- [ ] Key format and naming conventions
+- [ ] How the generator creates keyed registrations
+- [ ] Resolving decorated vs undecorated instances
+- [ ] Troubleshooting keyed service issues
+
+## Requirements
+
+DecoWeaver requires .NET 8.0+ runtime specifically because it leverages the keyed services feature introduced in that version for its internal implementation.
+
+## See Also
+
+- [How It Works](../core-concepts/how-it-works.md) - Understanding the generation process
+- [Interceptors](interceptors.md) - How interceptors redirect DI calls

docs/advanced/performance.md

@@ -0,0 +1,38 @@
+# Performance
+
+!!! info "Coming Soon"
+    This documentation is under development. Check back soon for performance benchmarks and optimization guidance.
+
+## Overview
+
+This page will cover:
+
+- Build-time performance characteristics
+- Runtime performance compared to reflection-based decorators
+- Memory footprint analysis
+- Benchmarks and comparisons
+- Performance optimization tips
+
+## Planned Content
+
+- [ ] Build-time generation performance metrics
+- [ ] Runtime overhead analysis (spoiler: zero!)
+- [ ] Comparison with reflection-based decorator libraries
+- [ ] Comparison with manual factory registration
+- [ ] Memory allocation analysis
+- [ ] Performance best practices
+- [ ] Benchmarking methodology
+
+## Key Performance Features
+
+DecoWeaver is designed for zero runtime overhead:
+
+- **No reflection** - All decorator wiring happens at compile time
+- **No assembly scanning** - Interceptors redirect specific call sites only
+- **No runtime registration** - DI container configured at build time via generated code
+- **Incremental generation** - Only regenerates when source changes
+
+## See Also
+
+- [How It Works](../core-concepts/how-it-works.md) - Understanding compile-time generation
+- [Requirements](../getting-started/requirements.md) - Runtime and SDK requirements

docs/advanced/troubleshooting.md

@@ -0,0 +1,53 @@
+# Troubleshooting
+
+!!! info "Coming Soon"
+    This documentation is under development. Check back soon for common issues and solutions.
+
+## Overview
+
+This page will provide solutions to common problems encountered when using DecoWeaver.
+
+## Planned Content
+
+- [ ] Generator not running
+- [ ] Decorators not being applied
+- [ ] Circular dependency errors
+- [ ] Generic type resolution issues
+- [ ] C# language version errors
+- [ ] IDE integration issues
+- [ ] Build warnings and how to resolve them
+- [ ] Diagnostic error codes (DECOW###)
+
+## Quick Diagnostics
+
+While detailed troubleshooting content is being developed, here are some quick checks:
+
+### Verify Installation
+```bash
+dotnet list package | grep DecoWeaver
+```
+
+### Check Generated Files
+Look in `obj/Debug/{targetFramework}/generated/DecoWeaver/` for generated interceptor code.
+
+### Verify C# Version
+Ensure your project targets C# 11 or later:
+```xml
+<LangVersion>11</LangVersion>
+```
+
+### Check Build Output
+Look for DecoWeaver diagnostics with code `DECOW###` in build output.
+
+## Getting Help
+
+If you encounter issues not covered here:
+
+1. Check existing [GitHub Issues](https://github.com/LayeredCraft/decoweaver/issues)
+2. Review the [Requirements](../getting-started/requirements.md) page
+3. Open a new issue with reproduction steps
+
+## See Also
+
+- [Requirements](../getting-started/requirements.md) - Prerequisites and configuration
+- [How It Works](../core-concepts/how-it-works.md) - Understanding the generation process

docs/api-reference/generated-code.md

@@ -0,0 +1,43 @@
+# Generated Code
+
+!!! info "Coming Soon"
+    This documentation is under development. Check back soon for detailed information about the structure of generated interceptor code.
+
+## Overview
+
+This page will cover:
+
+- Structure of generated interceptor files
+- How interceptors redirect DI registration calls
+- Understanding `[InterceptsLocation]` attributes
+- Generated factory methods for decorator chains
+- Keyed service registration patterns
+
+## Planned Content
+
+- [ ] File naming and organization (`DecoWeaver.Interceptors.ClosedGenerics.g.cs`)
+- [ ] Interceptor method signatures
+- [ ] `[InterceptsLocation]` attribute usage
+- [ ] Factory pattern for applying decorators
+- [ ] Keyed service registration code
+- [ ] How to read and debug generated code
+- [ ] Generated code versioning
+
+## Locating Generated Files
+
+Generated interceptor code can be found in:
+```
+obj/Debug/{targetFramework}/generated/DecoWeaver/DecoWeaver.Generator/DecoWeaver.Interceptors.ClosedGenerics.g.cs
+```
+
+## IDE Support for Generated Files
+
+- **Visual Studio 2022**: Enable "Show generated files" in Solution Explorer options
+- **JetBrains Rider**: Files appear under "Generated Files" node
+- **VS Code**: Generated files visible in obj/ directory
+
+## See Also
+
+- [Interceptors](../advanced/interceptors.md) - Understanding C# 11+ interceptors
+- [How It Works](../core-concepts/how-it-works.md) - Generation process overview
+- [Keyed Services](../advanced/keyed-services.md) - Internal keyed services strategy

docs/contributing.md

@@ -81,9 +81,11 @@ We welcome pull requests for:
 5. **Run tests**
 
    ```bash
-   dotnet test
+   dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0
    ```
 
+   Note: The test project uses Microsoft Testing Platform (MTP) and targets multiple frameworks, so you must specify the framework.
+
 ## Project Structure
 
 ```
@@ -180,7 +182,7 @@ public async Task Generator_AppliesDecorators_ForClassWithAttribute(
 1. **Ensure all tests pass**
 
    ```bash
-   dotnet test
+   dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0
    ```
 
 2. **Build successfully**
@@ -249,15 +251,17 @@ refactor: simplify decorator resolution logic
 
 ### Running Tests
 
+The test project uses Microsoft Testing Platform (MTP) and targets multiple frameworks (net8.0, net9.0, net10.0), so you must specify the framework when running tests:
+
 ```bash
-# Run all tests
-dotnet test
+# Run all tests (net8.0)
+dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net8.0
 
-# Run specific test
-dotnet test --filter "FullyQualifiedName~DecoWeaverGeneratorTests.Generator_AppliesDecorators"
+# Run tests on net9.0
+dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net9.0
 
-# Run with verbose output
-dotnet test --logger "console;verbosity=detailed"
+# Run tests on net10.0
+dotnet run --project test/LayeredCraft.DecoWeaver.Generator.Tests/LayeredCraft.DecoWeaver.Generator.Tests.csproj --framework net10.0
 ```
 
 ### Adding Test Cases

docs/getting-started/installation.md

@@ -5,21 +5,23 @@
 Install DecoWeaver via the .NET CLI:
 
 ```bash
-dotnet add package DecoWeaver
+dotnet add package DecoWeaver --prerelease
 ```
 
 Or via Package Manager Console in Visual Studio:
 
 ```powershell
-Install-Package DecoWeaver
+Install-Package DecoWeaver -Prerelease
 ```
 
 Or add directly to your `.csproj` file:
 
 ```xml
-<PackageReference Include="DecoWeaver" Version="1.0.0" />
+<PackageReference Include="DecoWeaver" Version="1.0.0-beta.*" />
 ```
 
+Note: The full version includes a build number suffix added by the build system (e.g., `1.0.0-beta.123`).
+
 ## Package Contents
 
 The DecoWeaver NuGet package includes:

docs/getting-started/quick-start.md

@@ -5,7 +5,7 @@ Get started with DecoWeaver in 5 minutes by creating a simple logging decorator.
 ## Step 1: Install DecoWeaver
 
 ```bash
-dotnet add package DecoWeaver
+dotnet add package DecoWeaver --prerelease
 ```
 
 ## Step 2: Create Your Service

docs/index.md

@@ -19,7 +19,7 @@
 ## Installation
 
 ```bash
-dotnet add package DecoWeaver
+dotnet add package DecoWeaver --prerelease
 ```
 
 ## Quick Start

docs/usage/opt-out.md

@@ -0,0 +1,25 @@
+# Opt-Out Mechanisms
+
+!!! info "Coming Soon"
+    This documentation is under development. Check back soon for information about opting out of decorator application.
+
+## Overview
+
+This page will cover:
+
+- How to exclude specific decorators from being applied
+- Global opt-out mechanisms
+- Surgical opt-out for specific scenarios
+- Use cases for opting out of decoration
+
+## Planned Content
+
+- [ ] Opt-out attribute usage
+- [ ] Per-decorator exclusions
+- [ ] Assembly-level opt-out mechanisms (Phase 2)
+- [ ] Best practices for when to use opt-outs
+
+## See Also
+
+- [Class-Level Decorators](class-level-decorators.md) - Learn about applying decorators
+- [Multiple Decorators](multiple-decorators.md) - Managing multiple decorators

src/LayeredCraft.DecoWeaver.Generators/LayeredCraft.DecoWeaver.Generators.csproj

@@ -10,8 +10,8 @@
         <AssemblyName>$(PackageId)</AssemblyName>
         <RootNamespace>$(PackageId)</RootNamespace>
         <Title>$(PackageId)</Title>
-        <Description>DecoWeaver is a .NET incremental source generator that enables compile-time decorator registration using C# 11+ interceptors. Zero runtime overhead, type-safe decorator chains, and full open generic support for .NET dependency injection.</Description>
-        <PackageTags>source-generator;roslyn;dependency-injection;decorator-pattern;interceptors;compile-time;aop;di;ioc;dotnet</PackageTags>
+        <Description>DecoWeaver is a .NET incremental source generator that enables compile-time decorator registration using C# 11+ interceptors. Zero runtime overhead, type-safe decorator chains, and support for closed generic registrations in .NET dependency injection.</Description>
+        <PackageTags>source-generator;roslyn;dependency-injection;decorator-pattern;interceptors;compile-time;aop;di;ioc;dotnet;csharp;decorators;code-generation;cross-cutting;performance</PackageTags>
         <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
     </PropertyGroup>