Document shared-root publishing

docs/config.md

@@ -371,10 +371,48 @@ state:
 
 - `state.mode`: optional. Accepted values are `single_owner` and `shared_root`; default is `single_owner`.
 
-`single_owner` state records one pipeline/destination owner for each destination bundle path and is the state mode written by `run`.
+`single_owner` state records one pipeline/destination owner for each destination bundle path and is the default state mode.
 
 `shared_root` records multiple pipeline/destination owners in one destination root. Publish execution preserves unrelated owners, rejects path ownership conflicts, and writes shared-root destination state.
 
+Use `shared_root` when multiple configured destinations intentionally write disjoint output paths into the same backend root:
+
+```yaml
+pipelines:
+  - id: reports-source
+    source:
+      backend: local
+      path: /var/spool/distributor/reports
+    destinations:
+      - id: shared-root
+        backend: local
+        path: /srv/reports/shared
+        state:
+          mode: shared_root
+        publish:
+          source: true
+          html: false
+  - id: reports-html
+    source:
+      backend: local
+      path: /var/spool/distributor/reports
+    destinations:
+      - id: shared-root
+        backend: local
+        path: /srv/reports/shared
+        state:
+          mode: shared_root
+        publish:
+          source: false
+          html: true
+        transform:
+          markdown_to_html:
+            enabled: true
+            mode: sidecar
+```
+
+Every output path in a shared root belongs to exactly one `pipeline_id` and `destination_id`. A different owner planning the same path fails as a conflict.
+
 ## Reconciliation Policy
 
 ```yaml
@@ -503,6 +541,7 @@ Local examples:
 - `fan-out.yml`: local fan-out publication to source and HTML destinations.
 - `archive-and-latest.yml`: local archive plus fixed latest publication.
 - `merge-reconciliation.yml`: local HTML publication using merge reconciliation.
+- `shared-root.yml`: two local pipelines publishing disjoint outputs into one shared destination root.
 - `http-upload-local.yml`: local HTTP upload server config; requires `DISTRIBUTOR_EXAMPLE_UPLOAD_TOKEN` in the process environment or as a secret-file name before running `serve`.
 
 Environment-gated remote examples: