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

app/schemas.py

@@ -523,3 +523,72 @@ class UnshareOut(BaseModel):
 
     chat_id: uuid.UUID
     shared: bool
+
+
+class DocDraftCreate(BaseModel):
+    """``POST /api/doc-drafts`` body (phase 59, task 02): one completed
+    chat answer about to become documentation.
+
+    ``title`` arrives client-side as the last user question
+    (whitespace-collapsed, ≤120 chars — the chat auto-title convention,
+    phase 50); ``path`` as ``docs/<slug>.md``; ``body`` is the answer's
+    raw markdown (never HTML — the ``bor.chat.v1`` record's ``text``,
+    the phase-50/51 round-trip convention). The path guard-rails (task
+    02 — repo-relative, no ``..``, no absolute path) run in the API
+    layer so the 422 details stay fixed strings; the max lengths mirror
+    the ``documents`` table (title 500, path 1000).
+    """
+
+    title: str = Field(min_length=1, max_length=500)
+    path: str = Field(min_length=1, max_length=1000)
+    body: str = Field(min_length=1)
+
+
+class DocDraftUpdate(BaseModel):
+    """``PUT /api/doc-drafts/{token}`` body (phase 59, task 02): a
+    partial update — each field is replaced only when supplied (absent
+    keeps the row's current value; present must be non-empty — the
+    ``SavedChatUpdate`` optional-title pattern, extended to all three
+    editable fields). The same path guard-rails as create run in the
+    API layer when ``path`` is supplied.
+    """
+
+    title: str | None = Field(default=None, min_length=1, max_length=500)
+    path: str | None = Field(default=None, min_length=1, max_length=1000)
+    body: str | None = Field(default=None, min_length=1)
+
+
+class DocDraft(BaseModel):
+    """One draft row, full payload (create/get/put response, phase 59).
+
+    ``token`` is the URL credential (``/doc-edit.html?draft=<token>``
+    — the unguessable ``uuid4``, the share-token trust model, phase
+    51). ``status`` is ``draft`` until the push endpoint commits +
+    pushes the file, then ``pushed`` with ``branch`` / ``commit_sha``
+    recorded (both NULL while still a draft). Datetimes serialize
+    ISO-8601 on the wire (pydantic default).
+    """
+
+    token: uuid.UUID
+    title: str
+    path: str
+    body: str
+    status: str
+    branch: str | None = None
+    commit_sha: str | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class DocDraftPushed(BaseModel):
+    """``POST /api/doc-drafts/{token}/push`` success response (phase 59,
+    task 04): the commit + ``git push --ff-only`` landed — ``branch``
+    is the ``BOR_DOCS_BRANCH`` name and ``commit_sha`` the pushed
+    branch's new HEAD (the edit screen's branch + sha feedback; it must
+    equal ``git rev-parse <branch>`` in the repo — the E2E source of
+    truth is the bare repo's state, not the UI alone).
+    """
+
+    status: Literal["pushed"] = "pushed"
+    branch: str
+    commit_sha: str