docs: correct inaccurate API and model docstrings from PR review

Author: clean6378-max-it

api/composers.py

@@ -134,8 +134,11 @@ def get_composer(composer_id: str) -> tuple[Response, int] | Response:
         composer_id: Composer UUID.
 
     Returns:
-        Composer JSON from per-workspace storage or global fallback. 404 when not
-        found or schema drift blocks serving; 500 on unexpected failure.
+        Composer JSON from per-workspace storage or global fallback. Per-workspace
+        schema drift is logged and skipped before global fallback is attempted.
+        404 when the composer is absent from both stores (``{"error": "Composer not found"}``)
+        or when the global row fails validation (``{"error": "Composer schema drift"}``).
+        500 on unexpected failure.
     """
     try:
         workspace_path = resolve_workspace_path()

api/logs.py

@@ -33,7 +33,8 @@ def get_logs() -> tuple[Response, int] | Response:
     """List chat logs from global and per-workspace storage (GET /api/logs).
 
     Returns:
-        JSON array of log summary objects (id, title, timestamp, etc.). 500 on
+        JSON ``{"logs": [<log summary>, ...]}`` where each summary has ``id``,
+        ``title``, ``timestamp``, etc. 500 with ``{"error": ..., "logs": []}`` on
         unexpected failure.
     """
     try:

api/pdf.py

@@ -49,10 +49,11 @@ def _safe_text(text: str) -> str:
 def generate_pdf() -> tuple[Response, int] | Response:
     """Render markdown chat content as a PDF download (POST /api/generate-pdf).
 
-    Body: ``{"markdown": "...", "title": "..."}``.
+    Body (optional): ``{"markdown": "...", "title": "..."}``. Missing keys
+    default to ``""`` and ``"Chat"`` respectively.
 
     Returns:
-        ``application/pdf`` attachment on success. 400/500 JSON errors on failure.
+        ``application/pdf`` attachment on success. 500 JSON error on failure.
     """
     try:
         body = request.get_json(silent=True) or {}

api/workspaces.py

@@ -169,13 +169,17 @@ def get_workspace_tabs(workspace_id: str) -> tuple[Response, int] | Response:
     """List conversation tabs for a workspace (GET /api/workspaces/<id>/tabs).
 
     Args:
-        workspace_id: Storage folder name or ``cli:<project_id>``.
+        workspace_id: Storage folder name, ``global`` for unassigned chats, or
+            ``cli:<project_id>``.
 
     Query params: ``summary=1`` for lightweight tab headers only; ``nocache=1`` to
     bypass cache on summary requests.
 
     Returns:
-        Tabs payload from :func:`services.workspace_tabs` helpers. 500 on failure.
+        Tabs payload from :func:`services.workspace_tabs` helpers (typically
+        ``{"tabs": [...]}`` with optional ``warnings``). May return 200 with an
+        empty ``tabs`` list when upstream SQLite reads fail silently; 404 when
+        global storage is missing; 500 on unexpected route-level failure.
     """
     if workspace_id.startswith("cli:"):
         try:

models/cli_session.py

@@ -26,7 +26,8 @@ def from_dict(cls, raw: dict[str, Any]) -> "CliSessionMeta":
             Validated :class:`CliSessionMeta`.
 
         Raises:
-            SchemaError: When ``latestRootBlobId`` is missing or not a string.
+            SchemaError: When ``latestRootBlobId`` is missing, falsey (e.g.
+            empty string or ``None``), or not a string.
         """
         raw = require_dict(raw, model="CliSessionMeta", field="meta")
         latest = require_truthy(