Add ObservableChangeSet.Create docs, instruction maintenance rule

Cache instructions: Added ObservableChangeSet.Create section with
8 overloads documented, 3 practical examples (sync event bridge,
async API loading, SignalR live updates), key behaviors explained.

List instructions: Added ObservableChangeSet.Create<T> section with
sync and async examples (FileSystemWatcher, async stream).

Main instructions: Added 'Maintaining These Instructions' section
requiring new operators to be added to instruction files, operator
behavior changes to update tables, new utilities/domain types to
be documented.

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

Author: dwcullop

.github/copilot-instructions.md

@@ -59,6 +59,15 @@ DynamicData follows [Semantic Versioning (SemVer)](https://semver.org/). Breakin
 - Adding required parameters to existing methods
 - Changing the default behavior of an existing overload
 
+## Maintaining These Instructions
+
+These instruction files are living documentation. **They must be kept in sync with the code.**
+
+- When a **new operator** is added, it **MUST** be added to the appropriate instruction file (`dynamicdata-cache.instructions.md` or `dynamicdata-list.instructions.md`) with its change reason handling table.
+- When an **operator's behavior changes**, update its table in the instruction file.
+- When a **new test utility** is added, update the test utilities reference in the main instructions and the appropriate `testing-*.instructions.md`.
+- When a **new domain type** is added to `Tests/Domain/`, add it to the Domain Types section.
+
 ## Repository Structure
 
 ```

.github/instructions/dynamicdata-cache.instructions.md

@@ -56,6 +56,78 @@ cache.Edit(updater =>
 });
 ```
 
+## ObservableChangeSet.Create — Implicit Cache Factory
+
+`ObservableChangeSet.Create` is the cache equivalent of `Observable.Create`. It gives you a `SourceCache` inside a lambda and returns `IObservable<IChangeSet<T,K>>` — the cache is created and disposed automatically per subscriber.
+
+This is the **preferred way to bridge imperative code into DynamicData** without managing a `SourceCache` lifetime yourself.
+
+```csharp
+// Synchronous — populate the cache, return a cleanup action
+IObservable<IChangeSet<Person, string>> people = ObservableChangeSet.Create<Person, string>(
+    cache =>
+    {
+        // Populate the cache — changes flow to subscribers automatically
+        cache.AddOrUpdate(new Person("Alice", 30));
+        cache.AddOrUpdate(new Person("Bob", 25));
+
+        // Return cleanup action (called on unsubscribe)
+        return () => { /* cleanup resources */ };
+    },
+    keySelector: p => p.Name);
+
+// Synchronous — return IDisposable for cleanup
+IObservable<IChangeSet<Device, Guid>> devices = ObservableChangeSet.Create<Device, Guid>(
+    cache =>
+    {
+        // Subscribe to an external event source and pump into the cache
+        var watcher = new DeviceWatcher();
+        watcher.DeviceAdded += (s, d) => cache.AddOrUpdate(d);
+        watcher.DeviceRemoved += (s, d) => cache.Remove(d.Id);
+        watcher.Start();
+
+        return Disposable.Create(() => watcher.Dispose());
+    },
+    keySelector: d => d.Id);
+
+// Async — useful for loading from APIs, databases, etc.
+IObservable<IChangeSet<Product, int>> products = ObservableChangeSet.Create<Product, int>(
+    async (cache, cancellationToken) =>
+    {
+        var items = await _api.GetProductsAsync(cancellationToken);
+        cache.AddOrUpdate(items);
+
+        // Set up SignalR for live updates
+        var connection = new HubConnectionBuilder().WithUrl("/products").Build();
+        connection.On<Product>("Updated", p => cache.AddOrUpdate(p));
+        connection.On<int>("Removed", id => cache.Remove(id));
+        await connection.StartAsync(cancellationToken);
+
+        return Disposable.Create(() => connection.DisposeAsync().AsTask().Wait());
+    },
+    keySelector: p => p.Id);
+```
+
+**Key behaviors:**
+- A new `SourceCache` is created **per subscriber** (cold observable)
+- The cache's `Connect()` is wired to the subscriber automatically
+- The lambda can populate the cache synchronously or asynchronously
+- On unsubscribe, cleanup runs and the cache is disposed
+- Exceptions in the lambda propagate as `OnError`
+
+**Overloads:**
+
+| Signature | Use when |
+|-----------|----------|
+| `Create(Func<ISourceCache, Action>, keySelector)` | Sync, cleanup is an Action |
+| `Create(Func<ISourceCache, IDisposable>, keySelector)` | Sync, cleanup is IDisposable |
+| `Create(Func<ISourceCache, Task<IDisposable>>, keySelector)` | Async setup |
+| `Create(Func<ISourceCache, CancellationToken, Task<IDisposable>>, keySelector)` | Async with cancellation |
+| `Create(Func<ISourceCache, Task<Action>>, keySelector)` | Async, cleanup is Action |
+| `Create(Func<ISourceCache, CancellationToken, Task<Action>>, keySelector)` | Async with cancellation, Action cleanup |
+| `Create(Func<ISourceCache, Task>, keySelector)` | Async, no explicit cleanup |
+| `Create(Func<ISourceCache, CancellationToken, Task>, keySelector)` | Async with cancellation, no cleanup |
+
 ## Changesets — The Core Data Model
 
 A changeset (`IChangeSet<TObject, TKey>`) is an `IEnumerable<Change<TObject, TKey>>` — a batch of individual changes.

.github/instructions/dynamicdata-list.instructions.md

@@ -62,6 +62,46 @@ list.Edit(inner =>
 });
 ```
 
+## ObservableChangeSet.Create — Implicit List Factory
+
+`ObservableChangeSet.Create<T>` (single type parameter, no key) is the list equivalent. It gives you a `SourceList` inside a lambda and returns `IObservable<IChangeSet<T>>`.
+
+```csharp
+// Synchronous — populate the list, return cleanup
+IObservable<IChangeSet<string>> logLines = ObservableChangeSet.Create<string>(
+    list =>
+    {
+        var watcher = new FileSystemWatcher("logs");
+        watcher.Changed += (s, e) =>
+        {
+            var newLines = File.ReadAllLines(e.FullPath);
+            list.Edit(inner => inner.AddRange(newLines));
+        };
+        watcher.EnableRaisingEvents = true;
+
+        return Disposable.Create(() => watcher.Dispose());
+    });
+
+// Async with cancellation
+IObservable<IChangeSet<LogEntry>> entries = ObservableChangeSet.Create<LogEntry>(
+    async (list, cancellationToken) =>
+    {
+        var stream = _client.GetLogStreamAsync(cancellationToken);
+        await foreach (var entry in stream.WithCancellation(cancellationToken))
+        {
+            list.Add(entry);
+        }
+
+        return Disposable.Empty;
+    });
+```
+
+**Key behaviors:**
+- A new `SourceList` is created **per subscriber** (cold observable)
+- No key selector needed (lists are unkeyed)
+- Same overload set as the cache version (sync, async, cancellable)
+- On unsubscribe, cleanup runs and the list is disposed
+
 ## List Changesets — The Core Data Model
 
 A list changeset (`IChangeSet<T>`) is an `IEnumerable<Change<T>>`. Each change has a different structure than cache changes.