docs: fix watcher field-registration pattern across all docs (#102)

All three docs (quickstart, watching, async) showed watcher.field() called
inside the context manager block, which raises RuntimeError at runtime. The
implementation enforces field registration before start() / __enter__. Unified
on the canonical two-step pattern: create watcher, register fields, then enter
the context manager. Also removed the contradictory "Or equivalently" block and
confusing "Wait —" note from watching.md Lifecycle section, and fixed the
Multiple watchers example which had the same error.

Closes #65

Co-authored-by: Claude <noreply@anthropic.com>

Author: zeevdr

sdk/docs/async.md

@@ -30,10 +30,11 @@ Same constructor options as `ConfigClient` — see [Configuration](configuration
 from opendecree import AsyncConfigClient
 
 async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
-    async with client.watch("tenant-id") as watcher:
-        fee = watcher.field("payments.fee", float, default=0.01)
-        enabled = watcher.field("payments.enabled", bool, default=False)
+    watcher = client.watch("tenant-id")
+    fee = watcher.field("payments.fee", float, default=0.01)
+    enabled = watcher.field("payments.enabled", bool, default=False)
 
+    async with watcher:
         # .value works the same
         print(fee.value)
 
@@ -47,9 +48,10 @@ async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
 Use `async for` instead of `for`:
 
 ```python
-async with client.watch("tenant-id") as watcher:
-    fee = watcher.field("payments.fee", float, default=0.01)
+watcher = client.watch("tenant-id")
+fee = watcher.field("payments.fee", float, default=0.01)
 
+async with watcher:
     async for change in fee.changes():
         print(f"{change.old_value} -> {change.new_value}")
 ```

sdk/docs/quickstart.md

@@ -61,14 +61,15 @@ with ConfigClient("localhost:9090", subject="myapp") as client:
 
 ```python
 with ConfigClient("localhost:9090", subject="myapp") as client:
-    with client.watch("tenant-id") as watcher:
-        fee = watcher.field("payments.fee", float, default=0.01)
+    watcher = client.watch("tenant-id")
+    fee = watcher.field("payments.fee", float, default=0.01)
 
-        print(fee.value)  # current value, always fresh
+    @fee.on_change
+    def on_fee_change(old: float, new: float):
+        print(f"Fee changed: {old} -> {new}")
 
-        @fee.on_change
-        def on_fee_change(old: float, new: float):
-            print(f"Fee changed: {old} -> {new}")
+    with watcher:
+        print(fee.value)  # current value, always fresh
 ```
 
 See [Watching](watching.md) for more patterns.

sdk/docs/watching.md

@@ -4,16 +4,17 @@ Live config subscriptions via `ConfigWatcher` and `WatchedField[T]`.
 
 ## Basic usage
 
-Create a watcher from a client. Register fields before entering the context manager:
+Create a watcher from a client. Register fields before starting the watcher:
 
 ```python
 from opendecree import ConfigClient
 
 with ConfigClient("localhost:9090", subject="myapp") as client:
-    with client.watch("tenant-id") as watcher:
-        fee = watcher.field("payments.fee", float, default=0.01)
-        enabled = watcher.field("payments.enabled", bool, default=False)
+    watcher = client.watch("tenant-id")
+    fee = watcher.field("payments.fee", float, default=0.01)
+    enabled = watcher.field("payments.enabled", bool, default=False)
 
+    with watcher:
         # Read current values
         print(fee.value)      # 0.025 (float, always fresh)
         print(enabled.value)  # True (bool)
@@ -79,29 +80,19 @@ The iterator blocks until a change arrives. It stops when the watcher exits.
 
 ## Lifecycle
 
-Register fields **before** the `with` block. Fields cannot be added after the watcher starts:
+Register fields **before** starting the watcher. Calling `field()` after `start()` raises `RuntimeError`:
 
 ```python
 watcher = client.watch("tenant-id")
 
 # Register fields first
 fee = watcher.field("payments.fee", float, default=0.01)
 
-# Then start
+# Then start — loads snapshot and subscribes
 with watcher:
     print(fee.value)
 ```
 
-Or equivalently:
-
-```python
-with client.watch("tenant-id") as watcher:
-    fee = watcher.field("payments.fee", float, default=0.01)
-    # ...
-```
-
-Wait — fields must be registered **before** `start()`. When using the two-line form, register between `watch()` and `with`. When using the one-line form, the watcher loads a snapshot on enter, so fields registered inside the `with` block will get their initial values from the snapshot.
-
 ## Auto-reconnect
 
 If the gRPC stream drops (server restart, network issue), the watcher automatically reconnects with exponential backoff:
@@ -119,11 +110,14 @@ You can create multiple watchers for different tenants:
 
 ```python
 with ConfigClient("localhost:9090", subject="myapp") as client:
-    with client.watch("tenant-a") as watcher_a:
-        with client.watch("tenant-b") as watcher_b:
-            fee_a = watcher_a.field("payments.fee", float, default=0.01)
-            fee_b = watcher_b.field("payments.fee", float, default=0.01)
-            # Both update independently
+    watcher_a = client.watch("tenant-a")
+    watcher_b = client.watch("tenant-b")
+    fee_a = watcher_a.field("payments.fee", float, default=0.01)
+    fee_b = watcher_b.field("payments.fee", float, default=0.01)
+
+    with watcher_a, watcher_b:
+        # Both update independently
+        print(fee_a.value, fee_b.value)
 ```
 
 ## Next steps