docs: clarify store transaction boundaries

src/wf_api/source_registry.py

@@ -58,7 +58,11 @@ class SourceRegistryStore(Protocol[RegistryT]):
 
 
 class AtomicJsonRegistryStore(Generic[RegistryT]):
-    """Filesystem implementation for small desired-registry documents."""
+    """Filesystem implementation for small desired-registry documents.
+
+    Saves replace one whole JSON file atomically, but there is no revision check
+    or cross-process compare-and-swap. Concurrent writers are last-writer-wins.
+    """
 
     def __init__(
         self,

src/wf_artifacts/runs/store.py

@@ -30,7 +30,12 @@ class RunStore:
 
 
 class FileRunStore(RunStore):
-    """JSON file-backed stopped-run store for local development and tests."""
+    """JSON file-backed stopped-run store for local development and tests.
+
+    The internal lock protects individual writes inside one process only.
+    `WorkflowRunApi.resume_run()` owns the same-process read/execute/write
+    critical section; multi-worker deployments need a transactional store.
+    """
 
     def __init__(self, root: Path) -> None:
         self.root = root

src/wf_artifacts/store.py

@@ -56,7 +56,12 @@ class WorkflowArtifactStore:
 
 
 class FileWorkflowArtifactStore(WorkflowArtifactStore):
-    """JSON file-backed artifact store for local development and tests."""
+    """JSON file-backed artifact store for local development and tests.
+
+    This store validates paths and performs simple file writes/deletes. API
+    services own multi-step policies such as "do not delete referenced
+    artifacts"; use a transactional store for multi-process safety.
+    """
 
     def __init__(self, root: Path) -> None:
         self.root = root

src/wf_sources_mcp/storage/store.py

@@ -54,6 +54,12 @@ class Store(AuthStore, CatalogStore):
 
 
 class FileAuthStore(AuthStore):
+    """Local plaintext JSON auth store for development and test deployments.
+
+    Admin surfaces keep payload values write-only, but this filesystem backend
+    does not encrypt secrets or coordinate cross-process writes.
+    """
+
     def __init__(self, root: Path) -> None:
         self.root = root
         self.root.mkdir(parents=True, exist_ok=True)
@@ -115,6 +121,12 @@ class FileAuthStore(AuthStore):
 
 
 class FileCatalogStore(CatalogStore):
+    """Local JSON cache for MCP catalog snapshots.
+
+    Catalog snapshots are a convenience cache, not authoritative desired state,
+    and writes are not cross-process transactional.
+    """
+
     def __init__(self, root: Path) -> None:
         self.root = root
         self.root.mkdir(parents=True, exist_ok=True)