Update README

Author: NikolayPianikov

AGENTS.md

@@ -7137,6 +7137,192 @@ To run the above code, the following NuGet packages must be added:
 
 For more hints, see [this](../README.md#setup-hints) page.
 
+## Customize the generated interface
+
+This example shows how to place a generated contract in a dedicated Contracts namespace.
+
+```c#
+using Pure.DI;
+
+DI.Setup(nameof(Composition))
+    .Bind().To<InvoiceGenerator>()
+    .Root<App>(nameof(App));
+
+var composition = new Composition();
+var app = composition.App;
+
+app.InvoiceId.ShouldBe("INV-0042");
+
+public class App(IMyInvoiceGenerator generator)
+{
+    public string InvoiceId { get; } = generator.Format(42);
+}
+
+namespace Contracts
+{
+    public partial interface IMyInvoiceGenerator;
+
+    [GenerateInterface(namespaceName: "Contracts", interfaceName: nameof(IMyInvoiceGenerator))]
+    public class InvoiceGenerator : IMyInvoiceGenerator
+    {
+        public string Format(int number) => $"INV-{number:0000}";
+    }
+}
+```
+
+To run the above code, the following NuGet package must be added:
+ - [Pure.DI](https://www.nuget.org/packages/Pure.DI)
+
+The example shows how to:
+- Generate an interface into a custom namespace
+- Rename the generated interface
+- Keep the contract separate from implementation details
+
+## Generate an interface from a class
+
+This example shows how a concrete service can generate a matching interface and be consumed through Pure.DI.
+
+```c#
+using Shouldly;
+using Pure.DI;
+
+DI.Setup(nameof(Composition))
+    .Bind().To<EmailSender>()
+    .Root<App>(nameof(App));
+
+var composition = new Composition();
+var app = composition.App;
+
+app.Provider.ShouldBe("smtp");
+app.Result.ShouldBe("sent:ops@contoso.com");
+
+public partial interface IEmailSender;
+
+[GenerateInterface]
+public class EmailSender : IEmailSender
+{
+    public string Provider => "smtp";
+
+    public string Send(string address) => $"sent:{address}";
+}
+
+public class App(IEmailSender sender)
+{
+    public string Provider { get; } = sender.Provider;
+
+    public string Result { get; } = sender.Send("ops@contoso.com");
+}
+```
+
+To run the above code, the following NuGet packages must be added:
+ - [Pure.DI](https://www.nuget.org/packages/Pure.DI)
+ - [Shouldly](https://www.nuget.org/packages/Shouldly)
+
+The example shows how to:
+- Generate an interface from a class
+- Bind the generated contract in Pure.DI
+- Resolve a consumer that depends on the interface
+
+## Generate interfaces with generics
+
+This example shows how generic members, nullable annotations, and events are preserved in a reporting scenario.
+
+```c#
+using Shouldly;
+using Pure.DI;
+
+DI.Setup(nameof(Composition))
+    .Bind().To<ReportFormatter>()
+    .Root<App>(nameof(App));
+
+var composition = new Composition();
+var app = composition.App;
+
+app.Formatted.ShouldBe("Order #42");
+app.Title.ShouldBe("Daily Report");
+
+public partial interface IReportFormatter;
+
+[GenerateInterface]
+public class ReportFormatter : IReportFormatter
+{
+    public string? Title { get; set; } = "Daily Report";
+
+    public event EventHandler? Changed;
+
+    public string? Format<T>(T value)
+        where T : class
+        => value?.ToString();
+
+    [IgnoreInterface]
+    public void Hidden() { }
+}
+
+public class App(IReportFormatter formatter)
+{
+    public string Title { get; } = formatter.Title ?? string.Empty;
+
+    public string Formatted { get; } = formatter.Format(new Order(42)) ?? string.Empty;
+}
+
+public class Order(int id)
+{
+    public override string ToString() => $"Order #{id}";
+}
+```
+
+To run the above code, the following NuGet packages must be added:
+ - [Pure.DI](https://www.nuget.org/packages/Pure.DI)
+ - [Shouldly](https://www.nuget.org/packages/Shouldly)
+
+The example shows how to:
+- Generate an interface for generic members
+- Preserve nullable annotations
+- Preserve events and generic constraints
+
+## Ignore members in the generated interface
+
+This example shows how to exclude internal-only members from a generated interface.
+
+```c#
+using Shouldly;
+using Pure.DI;
+
+DI.Setup(nameof(Composition))
+    .Bind().To<ApiClient>()
+    .Root<App>(nameof(App));
+
+var composition = new Composition();
+var app = composition.App;
+
+app.Endpoint.ShouldBe("https://api.contoso.com");
+
+public partial interface IApiClient;
+
+[GenerateInterface]
+public class ApiClient : IApiClient
+{
+    public string Endpoint => "https://api.contoso.com";
+
+    [IgnoreInterface]
+    public string GetAccessToken() => "internal-token";
+}
+
+public class App(IApiClient client)
+{
+    public string Endpoint { get; } = client.Endpoint;
+}
+```
+
+To run the above code, the following NuGet packages must be added:
+ - [Pure.DI](https://www.nuget.org/packages/Pure.DI)
+ - [Shouldly](https://www.nuget.org/packages/Shouldly)
+
+The example shows how to:
+- Mark members with IgnoreInterface
+- Keep only the intended contract surface
+- Use the generated interface in Pure.DI
+
 ## Composition root kinds
 
 Demonstrates different kinds of composition roots that can be created: public methods, private partial methods, and static roots. Each kind serves different use cases for accessing composition roots with appropriate visibility and lifetime semantics.

README.md

@@ -395,6 +395,11 @@ dotnet run
 - [OnNewInstance wildcard hint](readme/onnewinstance-wildcard-hint.md)
 - [ToString hint](readme/tostring-hint.md)
 - [Check for a root](readme/check-for-a-root.md)
+### Interfaces
+- [Customize the generated interface](readme/customize-the-generated-interface.md)
+- [Generate an interface from a class](readme/generate-an-interface-from-a-class.md)
+- [Generate interfaces with generics](readme/generate-interfaces-with-generics.md)
+- [Ignore members in the generated interface](readme/ignore-members-in-the-generated-interface.md)
 ### Advanced
 - [Composition root kinds](readme/composition-root-kinds.md)
 - [Factory with thread synchronization](readme/factory-with-thread-synchronization.md)
@@ -2038,7 +2043,7 @@ AI needs to understand the situation it’s in (context). This means knowing det
 | --------------- | ---- | ------ |
 | [AGENTS_SMALL.md](AGENTS_SMALL.md) | 62KB | 16K |
 | [AGENTS_MEDIUM.md](AGENTS_MEDIUM.md) | 106KB | 27K |
-| [AGENTS.md](AGENTS.md) | 387KB | 99K |
+| [AGENTS.md](AGENTS.md) | 391KB | 100K |
 
 For different IDEs, you can use the _AGENTS.md_ file as is by simply copying it to the root directory. For use with _JetBrains Rider_ and _Junie_, please refer to [these instructions](https://www.jetbrains.com/help/junie/customize-guidelines.html). For example, you can copy any _AGENTS.md_ file into your project (using _Pure.DI_) as _.junie/guidelines.md._
 ## How to contribute to Pure.DI

readme/SingletonDetails.md

@@ -91,7 +91,7 @@ partial class Singleton
   internal Singleton(Singleton parentScope)
   {
     if (Object.ReferenceEquals(parentScope, null)) throw new ArgumentNullException(nameof(parentScope));
-    _root = parentScope._root;
+    _root = parentScope._root ?? parentScope;
   }
 
   [MethodImpl(MethodImplOptions.AggressiveInlining)]

readme/accumulators.md

@@ -108,32 +108,32 @@ partial class Composition
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     get
     {
-      var perBlockTelemetryRegistry1 = new TelemetryRegistry();
-      var perBlockSqlDataSource5 = new SqlDataSource();
+      var perBlockTelemetryRegistry3 = new TelemetryRegistry();
+      var perBlockSqlDataSource7 = new SqlDataSource();
       if (_singletonNetworkDataSource64 is null)
         lock (_lock)
           if (_singletonNetworkDataSource64 is null)
           {
             NetworkDataSource _singletonNetworkDataSource64Temp;
             _singletonNetworkDataSource64Temp = new NetworkDataSource();
-            perBlockTelemetryRegistry1.Add(_singletonNetworkDataSource64Temp);
+            perBlockTelemetryRegistry3.Add(_singletonNetworkDataSource64Temp);
             Thread.MemoryBarrier();
             _singletonNetworkDataSource64 = _singletonNetworkDataSource64Temp;
           }
 
-      var transientSqlDataSource3 = new SqlDataSource();
+      var transientSqlDataSource5 = new SqlDataSource();
       lock (_lock)
       {
-        perBlockTelemetryRegistry1.Add(transientSqlDataSource3);
+        perBlockTelemetryRegistry3.Add(transientSqlDataSource5);
       }
 
-      var transientDashboard2 = new Dashboard(transientSqlDataSource3, _singletonNetworkDataSource64, perBlockSqlDataSource5);
+      var transientDashboard4 = new Dashboard(transientSqlDataSource5, _singletonNetworkDataSource64, perBlockSqlDataSource7);
       lock (_lock)
       {
-        perBlockTelemetryRegistry1.Add(transientDashboard2);
+        perBlockTelemetryRegistry3.Add(transientDashboard4);
       }
 
-      return (transientDashboard2, perBlockTelemetryRegistry1);
+      return (transientDashboard4, perBlockTelemetryRegistry3);
     }
   }
 }

readme/async-disposable-scope.md

@@ -147,7 +147,7 @@ partial class Composition: IDisposable, IAsyncDisposable
   internal Composition(Composition parentScope)
   {
     if (Object.ReferenceEquals(parentScope, null)) throw new ArgumentNullException(nameof(parentScope));
-    _root = parentScope._root;
+    _root = parentScope._root ?? parentScope;
     _lock = parentScope._lock;
     _disposables = new object[1];
   }
@@ -174,13 +174,13 @@ partial class Composition: IDisposable, IAsyncDisposable
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     get
     {
-      Func<Session> perBlockFunc577 = new Func<Session>(
+      Func<Session> perBlockFunc585 = new Func<Session>(
       [MethodImpl(MethodImplOptions.AggressiveInlining)]
       () =>
       {
         return new Session(this);
       });
-      return new Program(perBlockFunc577);
+      return new Program(perBlockFunc585);
     }
   }
 

readme/async-enumerable.md

@@ -89,14 +89,14 @@ partial class Composition
     get
     {
       [MethodImpl(MethodImplOptions.AggressiveInlining)]
-      async IAsyncEnumerable<IHealthCheck> EnumerationOf_transientIAsyncEnumerable374()
+      async IAsyncEnumerable<IHealthCheck> EnumerationOf_transientIAsyncEnumerable376()
       {
         yield return new MemoryCheck();
         yield return new ExternalServiceCheck();
         await Task.CompletedTask;
       }
 
-      return new HealthService(EnumerationOf_transientIAsyncEnumerable374());
+      return new HealthService(EnumerationOf_transientIAsyncEnumerable376());
     }
   }
 }

readme/async-root.md

@@ -76,29 +76,29 @@ partial class Composition
   [MethodImpl(MethodImplOptions.AggressiveInlining)]
   public Task<IBackupService> GetBackupServiceAsync(CancellationToken cancellationToken)
   {
-    Task<IBackupService> transientTask219;
+    Task<IBackupService> transientTask221;
     // Injects an instance factory
-    Func<IBackupService> perBlockFunc220 = new Func<IBackupService>(
+    Func<IBackupService> perBlockFunc222 = new Func<IBackupService>(
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     () =>
     {
       return new BackupService(new FileStore());
     });
-    Func<IBackupService> localFactory = perBlockFunc220;
+    Func<IBackupService> localFactory = perBlockFunc222;
     // Injects a task factory creating and scheduling task objects
-    TaskFactory<IBackupService> perBlockTaskFactory221;
+    TaskFactory<IBackupService> perBlockTaskFactory223;
     CancellationToken localCancellationToken = cancellationToken;
-    TaskCreationOptions transientTaskCreationOptions225 = TaskCreationOptions.None;
-    TaskCreationOptions localTaskCreationOptions = transientTaskCreationOptions225;
-    TaskContinuationOptions transientTaskContinuationOptions226 = TaskContinuationOptions.None;
-    TaskContinuationOptions localTaskContinuationOptions = transientTaskContinuationOptions226;
-    TaskScheduler transientTaskScheduler227 = TaskScheduler.Default;
-    TaskScheduler localTaskScheduler = transientTaskScheduler227;
-    perBlockTaskFactory221 = new TaskFactory<IBackupService>(localCancellationToken, localTaskCreationOptions, localTaskContinuationOptions, localTaskScheduler);
-    TaskFactory<IBackupService> localTaskFactory = perBlockTaskFactory221;
+    TaskCreationOptions transientTaskCreationOptions227 = TaskCreationOptions.None;
+    TaskCreationOptions localTaskCreationOptions = transientTaskCreationOptions227;
+    TaskContinuationOptions transientTaskContinuationOptions228 = TaskContinuationOptions.None;
+    TaskContinuationOptions localTaskContinuationOptions = transientTaskContinuationOptions228;
+    TaskScheduler transientTaskScheduler229 = TaskScheduler.Default;
+    TaskScheduler localTaskScheduler = transientTaskScheduler229;
+    perBlockTaskFactory223 = new TaskFactory<IBackupService>(localCancellationToken, localTaskCreationOptions, localTaskContinuationOptions, localTaskScheduler);
+    TaskFactory<IBackupService> localTaskFactory = perBlockTaskFactory223;
     // Creates and starts a task using the instance factory
-    transientTask219 = localTaskFactory.StartNew(localFactory);
-    return transientTask219;
+    transientTask221 = localTaskFactory.StartNew(localFactory);
+    return transientTask221;
   }
 }
 ```

readme/auto-scoped.md

@@ -146,7 +146,7 @@ partial class Composition
   internal Composition(Composition parentScope)
   {
     if (Object.ReferenceEquals(parentScope, null)) throw new ArgumentNullException(nameof(parentScope));
-    _root = parentScope._root;
+    _root = parentScope._root ?? parentScope;
     _lock = parentScope._lock;
   }
 
@@ -155,18 +155,18 @@ partial class Composition
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     get
     {
-      Func<IListeningSession> perBlockFunc585 = new Func<IListeningSession>(
+      Func<IListeningSession> perBlockFunc593 = new Func<IListeningSession>(
       [MethodImpl(MethodImplOptions.AggressiveInlining)]
       () =>
       {
-        IListeningSession transientIListeningSession586;
+        IListeningSession transientIListeningSession594;
         Composition localParentScope = this;
         // Create a child scope so scoped services (PlaybackQueue) are unique per session.
         var localScope = new Composition(localParentScope);
-        transientIListeningSession586 = localScope.Session;
-        return transientIListeningSession586;
+        transientIListeningSession594 = localScope.Session;
+        return transientIListeningSession594;
       });
-      return new MusicApp(perBlockFunc585);
+      return new MusicApp(perBlockFunc593);
     }
   }