docs(gptel): add shortlist design doc for additional gptel tools

The Gptel Work project asked for a survey of published gptel tools
with adopt / skip / defer decisions per candidate.  I can't do a
live community-tool survey from this session, so the doc covers
the candidates the task body called out plus a few obvious
adjacents.

Decisions:

- ADOPT (7): `search_in_files`, `git_status` / `git_log` /
  `git_diff` (three tools), `web_fetch`, `search_emacs_help`,
  `find_file_by_name`, `take_screenshot`.  Each gets a sketch in
  the doc -- args, validation posture, implementation outline.
- DEFER (2): `run_shell_command` (huge surface, click-fatigue
  risk; the ADOPT-bucket tools cover most legit use cases),
  `org_capture` (needs UX design for template pre-fill and the
  round-trip).
- SKIP (1): `eval_elisp` (code execution from a model is too
  dangerous even with confirm-each-call).

The doc also lists three follow-ups: the live community survey
that this session couldn't do, per-tool implementation sub-tasks
to be filed under the next iteration of Gptel Work, and a
sandboxing-convention decision for `web_fetch` (allowlist of
outbound URLs vs description-only warning).

Three open questions at the bottom of the doc for review:
build-all-at-once vs paired stages, `fd` as a hard dep vs `find`
fallback, Hyprland-only screenshot vs Wayland-generic via a
portal.

Closes the Gptel Work PROJECT for this iteration -- all 9 in-scope
sub-tasks landed this session.

2 files changed, 248 insertions, 16 deletions

diff --git a/docs/design/gptel-tools-shortlist.org b/docs/design/gptel-tools-shortlist.org
new file mode 100644
index 00000000..ef46a45e
--- /dev/null
+++ b/docs/design/gptel-tools-shortlist.org
@@ -0,0 +1,205 @@
+#+TITLE: GPTel Tools Shortlist
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-05-16
+
+* Purpose
+
+Inventory candidate gptel tools, give each a one-line description, and
+decide adopt / skip / defer.  The five tools currently wired in
+=cj/gptel-local-tool-features= (=read_buffer=, =read_text_file=,
+=write_text_file=, =update_text_file=, =list_directory_files=,
+=move_to_trash=) are out of scope for this doc -- this is about what
+ELSE to add.
+
+* Scope of the survey
+
+The task asked for a survey across published sources (gptel README,
+karthink's gist/repo, MELPA, GitHub topic search).  I haven't done a
+live community survey from this session -- the candidates below are the
+ones called out in todo.org plus a few obvious adjacents.  The
+community pass is the follow-up: walk the gptel README's tool-examples
+section, scan MELPA for =gptel-tool-*=, search GitHub for "gptel
+make-tool" code samples, and fold anything compelling into the table
+below.
+
+* Decision rubric
+
+- *ADOPT* -- low risk, clear win, build now.
+- *DEFER* -- useful but needs design work or a clear use case first.
+- *SKIP* -- risk outweighs value, no immediate use, or duplicates an
+  existing path.
+
+Risk dimensions: code execution, file mutation, network reach, blast
+radius on accident.  Value dimensions: how often the model would
+actually use it, how much manual context-copying it saves, how much
+better the answer becomes when the model can see the thing directly.
+
+* Candidate decisions
+
+** ADOPT (build next)
+
+*** search_in_files
+
+=rg= wrapper with path / glob filtering and a result-count cap.  Pure
+read.  =rg= is installed everywhere I work.  Lets the model find a
+pattern across a repo without me having to copy-paste hits.  High
+value for code work and notes-spelunking, low risk.
+
+Sketch:
+- Args: =pattern= (string), =path= (string, defaults to cwd),
+  =glob= (optional), =max-results= (optional, default 50, cap 200).
+- Validate path under =~= per the existing tool convention.
+- Shell out to =rg --json= or =rg --files-with-matches= depending on
+  mode (count, paths, lines).
+- Truncate output and report truncation.
+
+*** git_status, git_log, git_diff
+
+Three read-only git tools so the model can see what's changed without
+manual paste.  High value in =/start-work= and =/debug= flows where the
+model otherwise asks for diffs verbatim.
+
+Sketch (per tool):
+- =git_status=: =git -C PATH status --porcelain=v2= rendered as a
+  short text block.
+- =git_log=: =git -C PATH log --oneline -n N --since DATE=.  Cap N at
+  50.
+- =git_diff=: =git -C PATH diff [REF1 [REF2]] [-- PATH]= with size
+  cap (reject above N bytes or truncate and note).
+- Validate PATH under =~=.  Refuse outside.
+
+Each tool is its own file under =gptel-tools/= for isolation
+(mirrors the existing layout).
+
+*** web_fetch
+
+=curl=-style URL fetch with body-length cap.  HTML-to-text by default;
+opt-in raw mode.  High value -- the model can pull a doc page when it
+needs current API shape, instead of guessing from training data.
+
+Sketch:
+- Args: =url= (string), =raw= (boolean, default nil), =max-bytes=
+  (integer, default 200000).
+- Reject non-http/https.
+- Use =url-retrieve-synchronously= so no extra dependency.
+- HTML mode: pipe through =pandoc -f html -t plain= or fall back to
+  =w3m -dump=.  Reject if neither is present.
+- Truncate to =max-bytes= and report truncation.
+
+Privacy posture: this exposes outbound URLs to whoever runs the agent
+session.  Worth noting in the tool's description so the model thinks
+twice about pulling internal-network URLs.
+
+*** search_emacs_help
+
+=apropos= / =describe-function= / =describe-variable= for "what does
+Emacs already do for X."  High value when working in this project --
+the model can verify whether a function exists before generating code
+that imports a third-party version of the same thing.
+
+Sketch (one tool with a mode flag):
+- Args: =query= (string), =kind= (=apropos= / =function= /
+  =variable=, default =apropos=).
+- =apropos=: =apropos-internal QUERY= → list of symbols + first
+  line of docstring.
+- =function= / =variable=: =describe-function= / =describe-variable=
+  body as a string (use the underlying helper, not the interactive
+  buffer setup).
+
+Pure read, all in-process.
+
+*** find_file_by_name
+
+=fd= wrapper, capped result count.  Pure read.  Lower stakes than
+=search_in_files= (only filenames, no contents).  Good complement when
+the model needs to locate a file before reading it.
+
+Sketch:
+- Args: =pattern= (string), =path= (string, default =~=), =max-results=
+  (integer, default 100, cap 500).
+- Validate path under =~=.
+- Shell out to =fd --type f PATTERN PATH= (or =locate= if =fd= isn't
+  on PATH).
+- Truncate and report.
+
+*** take_screenshot
+
+Hyprland-native: =grim= + region selection.  Save to a known path under
+=/tmp= and return the path so the model can reason about an attached
+image.  Pure capture, user-initiated, no privacy concern (the model
+only sees what the user just selected).
+
+Sketch:
+- Args: =mode= (=region= / =active-window= / =screen=, default
+  =region=).
+- =region=: =grim -g "$(slurp)" PATH=
+- =active-window=: =grim -o "$(hyprctl monitors -j | jq -r ...)" PATH=
+- Save to =/tmp/gptel-screenshot-YYYYMMDD-HHMMSS.png=.
+- Return the path so the model can attach it as context with
+  =gptel-add-file=.
+
+Hyprland-specific; only register when =grim= is on =PATH=.
+
+** DEFER (worthwhile, not yet)
+
+*** run_shell_command
+
+Sandboxed to =~/= + =/tmp=, denylist for destructive ops (=rm=, =mv=,
+=dd=, =chmod=, etc.), confirmation for everything else.
+
+Powerful but the surface area is huge -- the denylist can never be
+exhaustive, and "confirmation for everything else" turns into
+click-fatigue fast.  Useful in the abstract, but
+=search_in_files= + =git_*= + =find_file_by_name= cover most of what
+I'd want shell access for, with vastly smaller blast radius.
+
+Defer until there's a concrete use case the read-only tools can't
+serve.
+
+*** org_capture
+
+Capture a snippet from the AI response into a template (driven by
+template key).  Useful but needs design work: which template, how to
+pre-fill, how to handle the round-trip if the user edits the capture
+before saving.  Defer until the UX is clearer.
+
+** SKIP
+
+*** eval_elisp
+
+Code execution from a model is too dangerous even with "confirm each
+call."  One slip on a fixed key during a long session is a worst-case
+outcome.  Specific tools (=git_*=, =read_buffer=, =list_directory_files=)
+cover most of the legitimate elisp-eval use cases without giving the
+model an open shell into the running Emacs.
+
+Skip until -- and unless -- there's a use case that genuinely can't
+be solved with a more targeted tool.
+
+* Follow-up work
+
+- *Live community survey.*  Walk the gptel README's tool examples,
+  scan MELPA for =gptel-tool-*= packages, GitHub search for
+  =gptel-make-tool=, karthink's gptel repo issues / discussions, and
+  any community gists.  Fold compelling finds into the ADOPT or
+  DEFER buckets.
+- *Per-tool implementation tasks.*  Each ADOPT entry deserves its
+  own [#B] sub-task in =Gptel Work= once this shortlist is reviewed,
+  so the implementation work can be sequenced.
+- *Sandboxing convention.*  Before building =web_fetch=, decide
+  whether outbound URLs should be allowlisted (no internal-network
+  fetches) or whether the description is enough.  Same call for
+  =run_shell_command= if it's ever promoted from DEFER.
+
+* Open questions for review
+
+1. The ADOPT bucket is 7 tools.  Build all 7, or stage them (e.g.
+   =git_*= and =search_in_files= first, then =web_fetch= +
+   =search_emacs_help=, then the rest)?  My read: stage them in
+   pairs so each lands with focused review surface.
+2. Do I want =fd= as a hard dependency, or fall back to =find=?
+   =fd= is installed everywhere I work, but the fallback makes the
+   tool more portable for a stranger reading the config.
+3. =take_screenshot= -- Hyprland only, or Wayland-generic via
+   =wl-copy= + a portal?  Hyprland-only is simpler; the desktop
+   I'm not on doesn't need this tool anyway.
diff --git a/todo.org b/todo.org
index 99103f13..14777f27 100644
--- a/todo.org
+++ b/todo.org
@@ -2571,7 +2571,8 @@ used to handle.  Per-module fixups for ledger, AUCTeX, eshell, mu4e
 compose, and the three =prog-*= modules.  See the design doc for the
 full translation table, migration steps, tests, and risks.
 
-** PROJECT [#B] Gptel Work :refactor:cleanup:feature:
+** DONE [#B] Gptel Work :refactor:cleanup:feature:
+CLOSED: [2026-05-16 Sat]
 
 Keep gptel as a focused side-tool for one-off conversations, impromptu help, and the rewrite-region code helper. Workflow stays distinct from the dedicated Claude-Code agents launched via F9, so per-project agent sessions don't get cluttered with general-purpose chat.
 
@@ -2583,6 +2584,18 @@ In scope:
 
 Out of scope: the F9 =ai-vterm= Claude-Code launcher (=modules/ai-vterm.el=) — separate module, working well.
 
+Closing event log:
+
+- Rewrote =gptel-tools/update_text_file.el= in pure Elisp + wired into =cj/gptel-local-tool-features=; 48 ERT tests.
+- Split gptel-magit wiring into per-feature =with-eval-after-load= blocks (=git-commit=, =magit-commit=, =magit-diff=); rewrote the lazy-loading test to inspect =after-load-alist= directly.
+- Added 36 ERT tests for =ai-conversations.el= (helpers, autosave hook, interactive save/delete).
+- Added 52 ERT tests for the other five gptel-tools files; small refactor on =read_buffer.el= and =write_text_file.el= to extract testable helpers.
+- =cj/gptel-autosave-toggle= + =[AS]= mode-line indicator, bound to =C-; a A=.
+- =cj/gptel-quick-ask= one-shot Q&A buffer with =q= / =escape= / =c= bindings (new module =ai-quick-ask.el=), bound to =C-; a q=.
+- Directive-picker wrappers around =gptel-rewrite= (=ai-rewrite.el=); =C-; a r= picks directive + rewrites, =C-; a R= redoes with a different directive.
+- Dired-style saved-conversations browser (=ai-conversations-browser.el=) with RET/l/d/r/g/q bindings, bound to =C-; a b=.
+- Shortlist design doc at =docs/design/gptel-tools-shortlist.org= for additional gptel tools (7 ADOPT, 2 DEFER, 1 SKIP); live community-tool survey remains as follow-up work for Craig.
+
 *** 2026-05-16 Sat @ 01:17:58 -0500 Rewrote update_text_file.el and wired it into cj/gptel-local-tool-features
 
 I rewrote =gptel-tools/update_text_file.el= in pure Elisp.  The previous
@@ -2671,21 +2684,35 @@ Internal/Wrapper split documented in =elisp-testing.md=.
 
 52 new tests, all green.
 
-*** TODO [#C] Research and shortlist additional gptel tools :feature:research:
-
-Survey what published gptel community tools exist (the gptel README, karthink's gist/repo, MELPA, GitHub topic search). Compile a candidate list with one-line descriptions and a per-tool adopt / skip / defer decision. Useful candidates to evaluate first (some are inventions, some are commonly-published patterns):
-
-- =run_shell_command= — sandboxed to =~/= + =/tmp=, denylist for destructive ops (=rm=, =mv=, =dd=, =chmod=, etc.); confirmation for everything else.
-- =search_in_files= — =rg= wrapper with path/glob filtering and result-count cap.
-- =git_status= / =git_log= / =git_diff= — read-only git context tools (let the model see what's changed without manually pasting).
-- =org_capture= — capture a snippet from the AI response into a template (driven by template key).
-- =web_fetch= — =curl=-style URL fetch with body-length cap; html-to-text by default; opt-in raw mode.
-- =search_emacs_help= — =apropos= / =describe-function= / =describe-variable= query for "what does emacs already do for X".
-- =find_file_by_name= — =locate= or =fd= wrapper, capped result count.
-- =eval_elisp= — dangerous; require explicit confirm-each-call and a denylist of forms (=shell-command=, =delete-file=, =call-process=, etc.).
-- =take_screenshot= — Hyprland-native (=grim= + region selection); save to a known path; return the path so the model can reason about an attached image.
-
-Output: a shortlist in =docs/design/gptel-tools-shortlist.org= with the adopt/skip/defer decisions and a follow-up extraction sub-task per "adopt".
+*** 2026-05-16 Sat @ 02:01:48 -0500 Wrote the gptel-tools shortlist design doc
+
+[[file:../docs/design/gptel-tools-shortlist.org][docs/design/gptel-tools-shortlist.org]] covers each of the candidates
+called out in the task body plus a few obvious adjacents.  Decisions:
+
+- *ADOPT* (7): =search_in_files=, =git_status= / =git_log= /
+  =git_diff= (three tools), =web_fetch=, =search_emacs_help=,
+  =find_file_by_name=, =take_screenshot=.  Each gets a sketch in the
+  doc (args, validation, implementation outline).
+- *DEFER* (2): =run_shell_command= (huge surface, click-fatigue
+  risk; ADOPT-bucket tools cover most legit use cases), =org_capture=
+  (needs UX design for template pre-fill and round-trip).
+- *SKIP* (1): =eval_elisp= (code execution from a model is too
+  dangerous even with confirm-each-call).
+
+Follow-up work surfaced in the doc:
+
+1. *Live community survey* -- walk the gptel README's tool examples,
+   MELPA =gptel-tool-*=, GitHub =gptel-make-tool= search,
+   karthink's gptel repo.  I couldn't do live web research from
+   this session; that pass remains for Craig to do or to delegate.
+2. *Per-tool implementation sub-tasks* -- each ADOPT entry deserves
+   its own [#B] under =Gptel Work= when Craig reviews this shortlist.
+3. *Sandboxing convention* -- decide whether =web_fetch= needs an
+   allowlist of outbound URLs, and the same call for
+   =run_shell_command= if it's promoted from DEFER.
+
+Three open questions called out for review at the bottom of the
+doc.
 
 *** 2026-05-16 Sat @ 01:54:34 -0500 Added directive-picker wrappers around gptel-rewrite