durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/configuration/options.md

@@ -109,7 +109,34 @@ When Waterline is deployed against a shared database with multiple namespaces, s
 WATERLINE_NAMESPACE=production
 ```
 
-This injects a namespace filter into every visibility query so Waterline only shows workflows belonging to the configured namespace.
+This injects a namespace filter into every visibility query so Waterline only shows workflows belonging to the configured namespace. When set, Waterline also scopes all command operations (cancel, signal, terminate, update, repair, archive, and queries) to the configured namespace — a command targeting an instance or run that belongs to a different namespace will return a 404 instead of executing.
+
+### Command namespace scoping
+
+`WorkflowStub::load()`, `loadSelection()`, and `loadRun()` accept an optional `namespace` parameter:
+
+```php
+use Workflow\V2\WorkflowStub;
+
+// Load only if the instance belongs to the given namespace
+$stub = WorkflowStub::load('order-12345', namespace: 'production');
+
+// Load a specific run, scoped to namespace
+$stub = WorkflowStub::loadRun($runId, namespace: 'production');
+
+// Load a specific selection, scoped to namespace
+$stub = WorkflowStub::loadSelection('order-12345', $runId, namespace: 'production');
+```
+
+When `namespace` is `null` (the default), loading is unscoped and works against all namespaces — this preserves backward compatibility. When a namespace is provided, the query filters by namespace at the database level and throws `ModelNotFoundException` if the workflow does not exist in that namespace.
+
+The control plane command methods (`signal`, `cancel`, `terminate`, `update`, `repair`, `archive`) also accept `namespace` in their options array:
+
+```php
+$controlPlane->cancel('order-12345', [
+    'namespace' => 'production',
+]);
+```
 
 ### Task bridge namespace filtering
 

docs/defining-workflows/workflow-id.md

@@ -40,6 +40,8 @@ $sameSelectedRun = WorkflowStub::loadRun($runId);
 
 That instance-scoped selector is useful when another system already stored the public instance id and later wants to pin a historical run without changing the outer workflow address.
 
+All three loaders accept an optional `namespace` parameter. When provided, loading is scoped to the given namespace at the query level — a workflow belonging to a different namespace will not be found. See [Namespace Scoping](/configuration/options#namespace-scoping) for details.
+
 Instance-scoped current-run selection no longer trusts only the mutable `workflow_instances.current_run_id` pointer. `load($instanceId)`, `currentRunId()`, Waterline instance routes, and other instance-targeted current-run actions resolve the newest durable run in the instance chain, so continue-as-new navigation still lands on the right run even if that pointer is temporarily stale or null.
 
 That same distinction applies to query methods: