diff --git a/pageindex/parser/protocol.py b/pageindex/parser/protocol.py
index 76d7b0a..939af22 100644
--- a/pageindex/parser/protocol.py
+++ b/pageindex/parser/protocol.py
@@ -24,5 +24,8 @@ class ParsedDocument:
 
 @runtime_checkable
 class DocumentParser(Protocol):
-    def supported_extensions(self) -> list[str]: ...
-    def parse(self, file_path: str, **kwargs) -> ParsedDocument: ...
+    def supported_extensions(self) -> list[str]:
+        """Return the file extensions this parser handles (e.g. ['.pdf'])."""
+
+    def parse(self, file_path: str, **kwargs) -> ParsedDocument:
+        """Parse a file into a ParsedDocument (a flat list of ContentNode)."""
diff --git a/pageindex/storage/protocol.py b/pageindex/storage/protocol.py
index 427021b..5d7d107 100644
--- a/pageindex/storage/protocol.py
+++ b/pageindex/storage/protocol.py
@@ -4,15 +4,40 @@ from typing import Protocol, runtime_checkable
 
 @runtime_checkable
 class StorageEngine(Protocol):
-    def create_collection(self, name: str) -> None: ...
-    def get_or_create_collection(self, name: str) -> None: ...
-    def list_collections(self) -> list[str]: ...
-    def delete_collection(self, name: str) -> None: ...
-    def save_document(self, collection: str, doc_id: str, doc: dict) -> None: ...
-    def find_document_by_hash(self, collection: str, file_hash: str) -> str | None: ...
-    def get_document(self, collection: str, doc_id: str) -> dict: ...
-    def get_document_structure(self, collection: str, doc_id: str) -> list: ...
-    def get_pages(self, collection: str, doc_id: str) -> list | None: ...
-    def list_documents(self, collection: str) -> list[dict]: ...
-    def delete_document(self, collection: str, doc_id: str) -> None: ...
-    def close(self) -> None: ...
+    """Persistence contract for collections and their documents."""
+
+    def create_collection(self, name: str) -> None:
+        """Create a new collection; error if it already exists."""
+
+    def get_or_create_collection(self, name: str) -> None:
+        """Create the collection if absent; no-op if it already exists."""
+
+    def list_collections(self) -> list[str]:
+        """Return all collection names."""
+
+    def delete_collection(self, name: str) -> None:
+        """Delete a collection and all its documents."""
+
+    def save_document(self, collection: str, doc_id: str, doc: dict) -> None:
+        """Persist a document under a collection."""
+
+    def find_document_by_hash(self, collection: str, file_hash: str) -> str | None:
+        """Return the doc_id with this file hash in the collection, or None."""
+
+    def get_document(self, collection: str, doc_id: str) -> dict:
+        """Return a document's metadata."""
+
+    def get_document_structure(self, collection: str, doc_id: str) -> list:
+        """Return a document's tree structure."""
+
+    def get_pages(self, collection: str, doc_id: str) -> list | None:
+        """Return cached page content, or None if not cached."""
+
+    def list_documents(self, collection: str) -> list[dict]:
+        """Return metadata for all documents in a collection."""
+
+    def delete_document(self, collection: str, doc_id: str) -> None:
+        """Delete a single document from a collection."""
+
+    def close(self) -> None:
+        """Release any underlying resources (connections, handles)."""