feat(docs): save chat answers as docs — edit screen, commit + push to the .env docs branch

scripts/git_sync.py

@@ -10,14 +10,16 @@ No credentials are stored here; whatever the URL/SSH config supplies is
 used.
 
 This module is the only place the ``git`` CLI is invoked (A11: stdlib
-``subprocess`` only, no new packages).
+``subprocess`` only, no new packages) — every git command goes through
+:func:`run_git`: the clone/pull in :func:`clone_or_pull` and the
+docs-push sequence in :mod:`app.core.docs_push` (phase 59).
 """
 from __future__ import annotations
 
 import subprocess
 from pathlib import Path
 
-__all__ = ["GitSyncError", "clone_or_pull"]
+__all__ = ["GitSyncError", "clone_or_pull", "run_git"]
 
 
 class GitSyncError(RuntimeError):
@@ -40,14 +42,22 @@ def clone_or_pull(url: str, dest: Path | str) -> Path:
     dest = Path(dest)
     if not dest.exists() or not (dest / ".git").exists():
         dest.parent.mkdir(parents=True, exist_ok=True)
-        _run(["git", "clone", "--depth", "1", url, str(dest)], cwd=dest.parent)
+        run_git(["git", "clone", "--depth", "1", url, str(dest)], cwd=dest.parent)
     else:
-        _run(["git", "pull", "--ff-only"], cwd=dest)
+        run_git(["git", "pull", "--ff-only"], cwd=dest)
     return dest
 
 
-def _run(argv: list[str], cwd: Path) -> str:
-    """Run a git command, capturing output; raise GitSyncError on failure."""
+def run_git(argv: list[str], cwd: Path) -> str:
+    """Run one git command, capturing output; raise GitSyncError on failure.
+
+    The single ``git`` invocation point for the whole app (A11). Every
+    step of :func:`clone_or_pull` and of the docs-push sequence
+    (:mod:`app.core.docs_push`, phase 59) goes through here, so error
+    handling stays uniform: captured stdout on success, and
+    :class:`GitSyncError` carrying git's stderr on a non-zero exit (or
+    when the git binary is missing from PATH).
+    """
     try:
         proc = subprocess.run(argv, cwd=cwd, capture_output=True, text=True)
     except FileNotFoundError: