From 9c945fbe63446c9a16141a5108e7b7e2b0268724 Mon Sep 17 00:00:00 2001
From: Michael Heller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 4 Aug 2026 11:42:41 -0400
Subject: [PATCH] =?UTF-8?q?feat(docs):=20doc=20feedback=20loop=20=E2=80=94?=
 =?UTF-8?q?=20shell=20functions,=20palette=20entries,=20Matrix=20!qes=20do?=
 =?UTF-8?q?c=20verb?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Shell functions (turtle-shell-init.zsh):
  - _turtle_doc_feedback_bin() — locate turtle-doc-feedback binary
  - docfb <doc_ref> <sentiment> [comment] — submit feedback; emoji shortcuts (👍/👎/❓)
  - docfaq [<doc_ref>] — show Noetica-derived FAQ stubs
  - docdistill [<doc_ref>] — run Noetica distillation over feedback receipts

Palette (turtleterm.lua):
  - 📖 Doc feedback: submit (docfb)
  - 📖 Doc FAQ: show stubs (docfaq)
  - 📖 Doc FAQ: distill (docdistill)

Paired with prophet-platform feat/matrix-qes-doc-verb for !qes doc Matrix verb.
---
 assets/sourceos/shell/turtle-shell-init.zsh | 33 +++++++++++++++++++++
 assets/sourceos/turtleterm.lua              |  7 +++++
 2 files changed, 40 insertions(+)

diff --git a/assets/sourceos/shell/turtle-shell-init.zsh b/assets/sourceos/shell/turtle-shell-init.zsh
index 85808a69fbd..2a52732f40e 100644
--- a/assets/sourceos/shell/turtle-shell-init.zsh
+++ b/assets/sourceos/shell/turtle-shell-init.zsh
@@ -2092,6 +2092,39 @@ tkn() {
     python3 "$(_turtle_ticket_bin)" comment "$@"
 }
 
+# ── Doc feedback ───────────────────────────────────────────────────────────────
+
+_turtle_doc_feedback_bin() {
+    local _b
+    for _b in \
+        "${TURTLE_SOURCEOS_BIN:-$HOME/.local/share/sourceos/bin}/turtle-doc-feedback" \
+        "${${(%):-%x}:h}/turtle-doc-feedback"; do
+        [[ -x "$_b" ]] && { printf '%s' "$_b"; return; }
+    done
+    printf '%s' "$(dirname "${(%):-%x}")/turtle-doc-feedback"
+}
+
+# docfb <doc_ref> <up|down|question|neutral> [comment]
+#   Submit doc feedback; emoji shortcuts: 👍=up, 👎=down, ❓=question
+docfb() {
+    local _doc="${1:?Usage: docfb <doc_ref> <sentiment> [comment]}"; shift
+    local _sent="$1"; shift
+    # emoji → word mapping
+    case "$_sent" in
+        👍|+1|up)        _sent=up       ;;
+        👎|-1|down)      _sent=down     ;;
+        ❓|'?'|question) _sent=question ;;
+        *)               ;;
+    esac
+    python3 "$(_turtle_doc_feedback_bin)" submit "$_doc" "$_sent" "$@"
+}
+
+# docfaq [<doc_ref>]   — show derived FAQ stubs
+docfaq() { python3 "$(_turtle_doc_feedback_bin)" faq "$@" }
+
+# docdistill [<doc_ref>]  — run Noetica distillation over feedback
+docdistill() { python3 "$(_turtle_doc_feedback_bin)" distill "$@" }
+
 # Auto-start Matrix bridge daemon at shell init if config is present
 if [[ -f "${HOME}/.config/sourceos/matrix.yaml" ]] || \
    [[ -n "${MATRIX_ACCESS_TOKEN:-}" ]]; then
diff --git a/assets/sourceos/turtleterm.lua b/assets/sourceos/turtleterm.lua
index 773f0d70407..d7e8096a867 100644
--- a/assets/sourceos/turtleterm.lua
+++ b/assets/sourceos/turtleterm.lua
@@ -1471,6 +1471,10 @@ local PALETTE_COMMANDS = {
   { label = '🎫  Ticket: close (tkc)             —',                  id = 'ticket_close'    },
   { label = '🎫  Ticket: comment (tkn)           —',                  id = 'ticket_note'     },
   { label = '🎫  Ticket: summary                 —',                  id = 'ticket_summary'  },
+  -- Doc feedback
+  { label = '📖  Doc feedback: submit (docfb)   —',                  id = 'doc_feedback'    },
+  { label = '📖  Doc FAQ: show stubs (docfaq)   —',                  id = 'doc_faq'         },
+  { label = '📖  Doc FAQ: distill (docdistill)  —',                  id = 'doc_distill'     },
 }
 
 local function turtle_command_palette()
@@ -1590,6 +1594,9 @@ local function turtle_command_palette()
             ticket_close       = act.SendString('tkc '),
             ticket_note        = act.SendString('tkn '),
             ticket_summary     = act.SendString('ticket summary\n'),
+            doc_feedback       = act.SendString('docfb '),
+            doc_faq            = act.SendString('docfaq\n'),
+            doc_distill        = act.SendString('docdistill\n'),
           }
           local a = dispatch[id]
           if a then w:perform_action(a, p) end