path: root/todo.org

#+TITLE: Emacs Config
#+AUTHOR: Craig Jennings
#+ARCHIVE: %s::* Emacs Resolved

* Emacs Priority Scheme

Use priority to express impact and urgency, not task type. Bugs, refactors,
tests, chores, and features can all be high or low priority.

- =[#A]= Urgent risk or current workflow blocker. Use for credential exposure,
  security/privacy leaks, data loss, destructive behavior, startup breakage,
  failing tests that block work, or a feature/refactor that unblocks a core
  daily workflow.
- =[#B]= Important planned work. Use for concrete bugs, high-leverage
  architecture cleanup, brittle load-order/test gaps, dependency failures, or
  feature work with a clear design and expected near-term use.
- =[#C]= Useful but optional. Use for low-risk cleanup, ergonomics, smoke tests,
  investigations with limited current impact, or feature work that would improve
  the setup but is not yet a committed workflow.
- =[#D]= Someday/maybe or watchlist. Use for speculative features, tiny polish,
  upstream/package tracking, optimizations without current pain, or deferred
  ideas that should not compete with active maintenance.

The task status (the TODO keyword) tracks where a task sits in its lifecycle.
The active keywords are:
- =TODO= — open, not started.
- =PROJECT= — a top-level task that groups several subtasks; the children are the real work, and the project closes when they do. PROJECT lives only at the top task level (a =**= heading under a section), never at the second level or below. A subtask that itself has children stays =TODO= / =DOING=; it does not become a nested PROJECT.
- =DOING= — actively in progress.
- =WAITING= — blocked on something external (a person, an upstream release).
- =VERIFY= — the code is done; only Craig's hands-on check or a pending answer remains. VERIFY tasks wait on Craig and are never auto-implemented.
- =STALLED= — blocked on an upstream issue outside our control.
- =DELEGATED= — handed to someone else to carry.
The done keywords (after the =|= in the sequence) are =DONE= (completed), =CANCELLED= (abandoned), and =FAILED= (attempted, could not be made to work).

For =PROJECT= headings, use the highest priority of the meaningful child work
inside the project. If a project only contains exploration or review, assign the
priority by the expected decision value rather than the number of files touched.

Use tags to describe the work shape. These six are the ONLY tags allowed on a
task. Do not invent topic, scope, or status tags — the heading and the parent
section already carry that context.
- =:bug:= means the current behavior is wrong or likely broken.
- =:feature:= means the task adds a new user-visible capability or workflow.
- =:refactor:= means the task changes structure/ownership without primarily
  changing behavior.
- =:test:= means the task primarily adds or fixes test coverage.
- =:quick:= means the task appears low effort and localized. It is a planning
  hint, not a promise; remove it if the task grows during implementation.
- =:solo:= means Claude can do the task end to end with no input from Craig:
  bounded scope, no design or preference call, and verifiable in the local
  setup (tests, byte-compile, launch). Tasks needing a policy/preference
  decision or a live remote do not get =:solo:=.

Tags are additive. For example, a small wrong-behavior fix can be
=:bug:quick:=, and a feature that requires internal restructuring can be
=:feature:refactor:=.
* Emacs Open Work
** PROJECT [#A] Manual testing and validation
Exercised once the phases above land.
*** TODO File-basename pickers show marginalia size/date annotations
What we're verifying: the eight pickers now carry a completion category and annotator (commit 4d644374), so marginalia should show a size + date suffix beside each candidate (a "dir" marker for directory candidates). The metadata is unit-tested; this is the live minibuffer render only Craig can see. Marginalia must be on (it is in this config). Eyeball each prompt, then =C-g=.
- =M-x cj/tmr-select-sound-file=. Expected: each timer-sound candidate shows a size + YYYY-MM-DD suffix.
- =C-h i= (browse Info files). Expected: each Info file shows size + date.
- =M-x cj/drill-start=. Expected: each flashcard .org shows size + date.
- =M-x cj/test-focus-add= then =M-x cj/test-focus-remove=. Expected: each test file shows size + date.
- =M-x cj/music-fuzzy-select-and-add=. Expected: files show size + date, directories show "dir" + date.
- =M-x cj/hugo-open-draft=. Expected: each draft shows size + date.
- =C-<f8>= (agenda for a single project). Expected: each project shows its todo.org's size + date (last-touched signal).
- Clone-dir picker: copy a git URL, then run the clone command with a single =C-u= prefix to reach the "Clone to:" picker. Expected: each clone dir shows "dir" + date; =C-g= to abort before it clones.
Expected: every picker annotates its candidates with size + date (or "dir" + date for directories); no picker errors, and the selected value still does what it did before (annotation is metadata-only).
*** DONE F12 opens the eshell-through-EAT terminal (dock, visual, colors, prompt, z)
CLOSED: [2026-06-27 Sat 12:50]
What we're verifying: F12 now opens and toggles eshell run through EAT (eat-eshell-mode), docked with the remembered geometry; F12 + C-; reach Emacs from inside it; and the eshell-in-eat features land. Wiring verified live; this is the hands-on check only Craig can run.
- Press F12 in a normal frame. Expected: an eshell docks (bottom or right per the column rule), prompt shows the git branch when in a repo, focus in it.
- Run a visual command (=htop= / =vim FILE= / =less FILE=). Expected: it renders full-screen in EAT, behaves like a real terminal.
- Run a colored command (=ls --color= / =git log --color=). Expected: colors look right, not doubled or garbled (the xterm-color-removal check).
- Run a failing command (=false=). Expected: the next prompt shows =[1]= (the exit-status segment).
- Run =z <dir-fragment>=. Expected: jumps to a zoxide-remembered directory.
- Press F12 again from inside. Expected: hides. Press F12 again. Expected: returns at the remembered size.
- From inside, press =C-; b= (a window-family leaf). Expected: the global prefix works, not typed into the shell.
Expected: F12 docks/hides/redocks one eshell-through-EAT terminal; visual commands render, colors are clean, the prompt shows branch + exit status, =z= jumps, and F12/C-; reach Emacs.
*** DONE ai-term agents run through EAT (launch, swap, detach/reattach)
CLOSED: [2026-06-27 Sat 12:50]
What we're verifying: agents now spawn in EAT instead of ghostel, with the tmux persistence intact. The spike + 157 unit tests pass; this is the live agent launch only Craig can run.
- =C-; a a= (or =C-; a s= to pick a project). Expected: an agent launches in an EAT terminal (buffer =agent [<project>]=) running the AI tool over tmux.
- With two agents open, press =M-SPC= repeatedly. Expected: it swaps to the next agent (M-SPC reaches Emacs from inside the EAT agent buffer).
- Kill an agent buffer (not the session), then re-open the same project. Expected: it reattaches the live tmux session (output intact), not a fresh agent.
- After an Emacs restart with =aiv-*= sessions alive, re-open a project. Expected: reattaches the detached session.
Expected: agents launch and render in EAT, M-SPC swaps from inside, and detach/reattach works exactly as it did on ghostel.
*** DONE ai-term next steps into and attaches a detached session
CLOSED: [2026-06-27 Sat 12:50]
What we're verifying: =C-; a n= (or =M-SPC=) cycles into a detached ai-term (alive in tmux, no Emacs buffer) and attaches it, not just live buffers. The pure logic is unit-tested; this is the live attach-on-landing check only Craig can run.
- Start agents in two projects so two ai-terms exist, then leave one detached (kill its Emacs buffer while the tmux session stays alive, or after an Emacs restart that leaves =aiv-*= sessions running).
- Confirm one is attached (a live =agent [...]= buffer) and one is detached (its =aiv-= tmux session is alive but has no buffer).
- Press =C-; a n= repeatedly to cycle through the agents.
Expected: the rotation includes the detached agent; landing on it recreates its terminal buffer and reattaches the tmux session (its live output appears), instead of skipping it. Order is stable (by buffer name) and wraps after the last.
*** VERIFY wttrin appears as a themeable app in theme-studio
What we're verifying: wttrin's four faces (=wttrin-instructions=, =wttrin-key=, =wttrin-mode-line-stale=, =wttrin-staleness-header=) now show up in the studio's package dropdown and render in a generic preview, after being added to =package-inventory.json= and the studio regenerated. Inventory + regen are verified mechanically (40 packages, all studio gates green); this is the visual confirm.
- Open the studio: =make -C scripts/theme-studio open= (or open =scripts/theme-studio/theme-studio.html= in Chrome).
- In the application/package dropdown, pick =wttrin=.
Expected: wttrin is listed, and its four faces are shown as editable rows in a generic preview. (If you later want the other local-checkout packages captured too, restart Emacs and re-run the inventory regen against the clean daemon.)
*** VERIFY EAT diff backgrounds read dark enough (Claude Code diffs)
What we're verifying: the added/removed line backgrounds in Claude Code diffs (=eat-term-color-22= / =-52=) now render at about half their former brightness (=#002f00= / =#2f0000=, down from =#005F00= / =#5F0000=) and read as comfortably dark while still clearly green/red. Themed via WIP.json + regenerated WIP-theme.el; live in the daemon. This is the darkness judgment only Craig can make.
- In a live agent (EAT) buffer, have Claude show a colored diff with both added and removed lines (e.g. ask it to edit a file).
- Look at the added-line green background and the removed-line red background.
Expected: both backgrounds read as dark/muted, not bright, with green and red still distinct. If still too bright or now too dark, say a direction and I retune the two hex values. If the brighter within-line word-highlight shades are still too bright, those are different eat-term-color indices I'd need to sample live (=C-h F= on a highlighted word) before darkening.
*** VERIFY transcription error log captures stderr on a failed run
What we're verifying: a failed transcription now writes the backend's stderr into the .log file the "Errored.  Logs in <file>" notification points at, and no hidden " *transcribe-stderr-*" buffer is left behind. The buffer-not-path fix and the drain-and-kill are unit-tested (39/39 green); this is the live failing-run check only Craig can run.
- Trigger a transcription that will fail — e.g. feed a corrupt/zero-byte audio file, or point the backend at a missing model — via the normal transcribe command.
- When the "Errored.  Logs in <file>" notification fires, open that .log file.
- Run =C-x C-b= (list-buffers) and scan for any buffer named like " *transcribe-stderr-...*".
Expected: the .log file contains the backend's actual error text (not just the header), and no " *transcribe-stderr-...*" buffer remains.
*** VERIFY Opening a video from dirvish plays it on repeat (mpv)
What we're verifying: a video opened from dirvish launches mpv with --loop-file=inf so it plays on repeat; non-video external files are unaffected. The routing, predicate, and arg list are unit-tested (15/15) and verified live; this is the visual playback only Craig can confirm.
- In dirvish, put point on a video file (.mp4 / .mkv / .webm) and press RET to open it.
Expected: mpv opens the video and loops it continuously (restarts at the end), detached so Emacs is not blocked.
- Open a non-video external file (a .pdf or .docx) from dirvish.
Expected: it opens in the OS default handler as before, not mpv.
Expected: videos open in mpv on repeat; other external files keep their normal handler.
*** VERIFY Google Keep v1 live setup and first fetch
What we're verifying: read-only v1 fetches real Keep notes and renders =data/keep.org= once the one-time gkeepapi + master-token setup is done. The code and 27 tests (12 Python + 15 ERT) are green; this is the live-credential step only Craig can run.
- Install the client into the interpreter =cj/keep-python= uses: =pip install gkeepapi= (or pipx).
- Obtain a Google master token (one-time, via gkeepapi's current login/gpsoauth flow against your account).
- Set your email:
#+begin_src emacs-lisp
(setq cj/keep-email "you@gmail.com")
#+end_src
- Add the token to =~/.authinfo.gpg= (line: =machine google-keep login you@gmail.com password <master-token>=), then clear the auth cache so the daemon sees it:
#+begin_src emacs-lisp
(auth-source-forget-all-cached)
#+end_src
- Fetch (or press =C-c k r=):
#+begin_src emacs-lisp
(cj/keep-refresh)
#+end_src
- Open the result with =C-c k o=.
Expected: =data/keep.org= lists your Keep notes, pinned first, each a header with title/body, labels as org tags, a property drawer (=:KEEP_ID:= / =:UPDATED:= / ...), and an "open in Keep" link. A missing piece (gkeepapi / token / auth) shows a clear =*Warnings*= message naming it, not a crash.
*** TODO theme-studio preview-locate discoverability read
What we're verifying: the locate hover/flash actually feels discoverable in a live frame — the subjective read the deterministic gates can't make.
- Open theme-studio in Chrome (=make theme-studio-open=, or open theme-studio.html).
- Hover several preview elements across the UI mock and a package pane.
- Click an on-pane element, then click an off-pane element.
Expected: hovering updates the preview-label info line immediately with "section > face — value" (no wait on the native tooltip); an on-pane click scrolls to and flashes the right assignment row; off-pane elements don't respond and their title explains why. The flow reads like a legend you can interrogate. If it feels broken or unclear, note where and reopen the relevant phase.
*** TODO reconcile-open-repos includes dot-named repos
What we're verifying: M-P (reconcile open repos) now visits repos whose directory name has a dot (mcp.el, capture.el, etc.), which the old "^[^.]+$" filter silently skipped. Fix in modules/reconcile-open-repos.el, live in the daemon; live-daemon check already confirmed discovery, this is the through-the-command spot-check.
- Run M-P (or M-x cj/reconcile-open-repos)
- Watch the per-repo progress / final summary
Expected: dot-named repos under ~/code (mcp.el, gptel-mcp.el, capture.el, google-contacts.el, …) appear in the reconciliation pass, not just dot-free ones.
*** TODO Safe-lightness guidance reads clearly
What we're verifying: the L_max marker and unsafe-band shade are legible and land in the right place when editing a covered face.
- Open the picker in OKLCH mode on region (or hl-line), with syntax colors assigned
- Read the L_max marker and the shaded unsafe band on the lightness slider
- Drag lightness up toward and past the marker
Expected: the marker is visible and correctly placed, the band above it reads as "unsafe," and crossing it is obvious; an out-of-scope face shows no marker.
*** TODO Safe tint actually reads in real Emacs
What we're verifying: a background tint the tool calls safe really keeps every token readable behind real syntax-colored text — the whole point of the worst-case floor.
- In the tool, set a covered face (e.g. region) to a tint at or just below its L_max with the worst-case readout showing PASS
- Build the theme and load it in Emacs, open a code buffer with varied syntax, and select a region spanning many token colors
- Read every token through the region highlight, paying attention to the limiting foreground the tool named
Expected: every token stays readable over the tint, including the limiting one; a tint pushed just past L_max (readout FAIL) shows a visibly strained or unreadable token, confirming the floor matches reality.
*** TODO Regenerate-replace reads as deliberate
What we're verifying: the count control clearly signals it rewrites the whole family, so replacing hand-added same-hue colors isn't a surprise.
- Add two unrelated colors at a similar hue so they share a strip
- Set that strip's count to 2
- Watch what happens to the two colors
Expected: the strip becomes a clean base±2 ramp, the two loose colors are gone, and the control made it obvious that's what it would do before you committed.
*** TODO Calibre curated ? menu and docked description
What we're verifying: the curated ? transient, the docked description, and the full dispatch all work in a live calibredb buffer.
- In a calibredb search buffer, press ? and confirm the curated menu (library / filter / sort / open / describe) appears.
- Press d or v to dock the selected book's description in a bottom-30% buffer; press q to dismiss it.
- Press H and confirm calibredb's full dispatch opens.
Expected: ? shows the curated menu, d/v dock the description (q dismisses), H opens the full calibredb dispatch.

*** TODO Signel: real incoming message raises a toast through the notify script
What we're verifying: the full receive path (signal-cli → signel --handle-receive → cj/signel--notify → notify script) fires on a real message.
- Make sure you are NOT viewing the sender's chat buffer.
- Have a real message sent to you on Signal (or send one from your phone to a second device thread that lands here).
Expected: a transient info toast titled "Signal: <sender>" with the message text (one line, truncated if long), no sound.

*** TODO Signel: actively-viewed chat stays quiet
What we're verifying: the suppression predicate gates the toast when you're reading that chat.
- Open the sender's chat buffer (=C-; M m=) and keep it the selected window in a focused frame.
- Have the same sender message you again.
Expected: the message renders in the buffer, but no desktop toast appears.

*** DONE Project-aware capture files into the right todo.org
CLOSED: [2026-06-24 Wed 11:48]
What we're verifying: C-c c t and C-c c b file into the current projectile project's todo.org under its "<Project> Open Work" header, and fall back to the global inbox outside a project.
- Inside a projectile project that has a todo.org, run C-c c t (Task), capture a test entry, and confirm it lands under "<Project> Open Work".
- Run C-c c b (Bug) similarly and confirm it lands as "* TODO [#C] ..." under the same header.
- Run a capture from outside any project (or a project with no todo.org) and confirm the global-inbox fallback with a warning.
Expected: in-project captures land in that project's Open Work; out-of-project captures fall back to the global inbox with a warning.
*** VERIFY C-c ; reaches the custom command family in a real terminal frame
What we're verifying: the TTY mirror prefix C-c ; reaches the same cj/custom-keymap as the GUI C-; prefix, so the whole command family works in a terminal. The unit tests + a live daemon eval already confirm both prefixes resolve to the one keymap; this is the end-to-end in an actual TTY frame, which the batch harness can't drive.
- Open a terminal Emacs frame: emacsclient -nw (or emacs -nw, or Emacs inside vterm/tmux)
- Press C-c ; L (pearl), C-c ; a (AI), C-c ; g (calendar) — the same leaf keys you use under C-; in GUI
- Confirm which-key shows the custom prefix under C-c ;
Expected: each C-c ; <leaf> runs the same command its C-; <leaf> counterpart runs in GUI; which-key lists the family under C-c ;. C-; itself stays working in GUI frames (unchanged).
*** VERIFY org-faces color set in theme-studio reaches the agenda
What we're verifying: editing an org-faces-* row in theme-studio, exporting, and deploying lands the new color on the real agenda's keyword/priority. The build-theme -> deftheme half and the live org-todo-keyword-faces / org-priority-faces wiring are already verified mechanically; this confirms the visual end-to-end with a human eye.
- Open theme-studio in Chrome and pick "org-faces" from the application dropdown (it sits beside elfeed and mu4e)
- Confirm the preview shows the focused agenda block over the auto-dim block, and that the rows read "todo", "priority a", etc.
- Edit org-faces-todo to an obviously different color (e.g. bright magenta) and export the theme to WIP.json
#+begin_src sh :results output
make -C /home/cjennings/.emacs.d deploy-wip
#+end_src
- Open the org agenda (or any todo.org buffer) and look at a TODO keyword
Expected: the TODO keyword renders in the color just set; the priority cookies and other keywords keep their own colors; an unfocused window shows the dimmed variants.
*** VERIFY ERC fires one mention notification and lists real servers
What we're verifying: a mention pops a single desktop notification (not two), and cj/erc-connected-servers lists only live server connections. Fixed in modules/erc-config.el; takes effect after an Emacs restart (not reloaded into the live IRC session).
- Restart Emacs and reconnect ERC
- Have someone mention your nick in a channel (or trigger erc-text-matched-hook)
- Run M-x cj/erc-connected-servers with one server connected and a few channels open
Expected: exactly one desktop notification per mention; cj/erc-connected-servers reports just the connected server(s), not every channel/query buffer.
*** VERIFY dwim-shell zip/backup/menu-key behave
What we're verifying: single-file zip makes a valid <name>.zip, the dated backup gets a real timestamp, and the dwim-shell menu is reachable on M-D in plain dired. Fixed in modules/dwim-shell-config.el, reloaded into the daemon.
- In dired, mark a single file, run the dwim-shell menu (M-D), pick Zip
- Mark a file, run the menu, pick "Backup with date"
- Open a plain dired buffer (not dirvish) and press M-D
Expected: zip produces foo.zip (a valid archive, openable); backup produces foo.ext.YYYYMMDD_HHMMSS.bak with a real date; M-D opens the dwim-shell command menu in plain dired (before the fix it did nothing there).
*** VERIFY orderless matching works inside a vertico session
What we're verifying: vertico-prescient no longer overrides completion-styles, so orderless's space-separated, out-of-order matching is live in the minibuffer (prescient still sorts). Fixed in modules/selection-framework.el, applied live in the daemon.
- Run a command with a vertico minibuffer (e.g. M-x, or C-x b)
- Type two space-separated fragments out of order, e.g. "mode buf" to match "switch-to-buffer-other-... mode" style candidates
Expected: candidates match on both fragments regardless of order (orderless), and the ordering still reflects prescient frecency. Before the fix, space-separated out-of-order input would not match.
*** VERIFY face-name buttons open describe-face
What we're verifying: the face names in the Face Diagnosis report are live buttons. The button text properties (action + face data) are confirmed in the daemon; this is the click/RET confirmation.
- Put point on themed text and run =C-h F= (=cj/describe-face-at-point=).
- In the *Face Diagnosis* buffer, move onto a face name (e.g. in the face stack or provenance) and press RET; also try mouse-1.
Expected: RET or a click on a face name opens that face's =describe-face= help. Non-face entries (anonymous specs) stay plain text. If a name isn't clickable, note which group it's in and reopen.
*** VERIFY latexmk compiles from C-c C-c
What we're verifying: the two activation fixes make the latexmk workflow usable end to end. A live .tex buffer already reports =TeX-command-default= "latexmk" and "LatexMk" in =TeX-command-list=; this is the actual compile.
- Open a small .tex document.
- Press C-c C-c (it should default to LatexMk without prompting through the other commands first), then RET to run it.
- Press C-c C-v to view the PDF.
Expected: C-c C-c runs latexmk and produces a PDF; C-c C-v opens it in the selected viewer. If C-c C-c still defaults to LaTeX or latexmk is missing from the command list, capture it and reopen.
*** VERIFY mu4e trash and refile land in synced maildirs
What we're verifying: the cmail trash-folder + per-message refile fix (shipped 2026-06-13, applies on next mu4e open) actually moves mail into folders mbsync syncs, and the gmail/dmail fail-safe blocks instead of stranding mail.
- Open mu4e (restart it if it was running before the fix) and enter the cmail account.
- On a cmail message, press =d= (mark for trash), then =x= to execute; confirm it lands in cmail/Trash and survives a sync (not a phantom /trash).
- On a cmail message, press =r= (refile) then =x=; confirm it lands in cmail/Archive.
- On a gmail (or dmail) message, press =r=.
Expected: cmail trash → cmail/Trash, cmail refile → cmail/Archive, both real maildirs mbsync syncs. Refile on gmail/dmail signals a user-error (no move) rather than offering to create an unsynced phantom folder. If any move targets a folder mbsync doesn't sync, capture it and reopen.
*** STALLED markdown live preview renders in the browser
What we're verifying: F2 in a markdown buffer runs the custom cj/markdown-preview (not markdown-mode's own command) and the impatient-mode strapdown preview actually renders. Fixed in modules/markdown-config.el, reloaded into the daemon.
- Open a .md file with some markdown content
- M-x cj/markdown-preview-server-start (starts simple-httpd on :8080)
- Press F2 in the markdown buffer
Expected: a browser opens http://localhost:8080/imp showing the rendered markdown, and edits to the buffer update the preview live.
Pressing F2 before starting the server gives a user-error telling you to start it.

#+begin_src cj: comment
  we should simply have the server start if it's not already started. 
#+end_src

*** STALLED ai-term wrap-teardown + shutdown end-to-end
What we're verifying: the three headless functions drive the rulesets wrap-it-up workflow correctly, including the real tmux/shutdown side effects the ERT tests can't exercise. The .emacs.d functions are in and unit-verified; the rulesets half (workflow + Stop hook) is already built. Test the countdown with a stubbed shutdown command first — do not power off during the check.
#+begin_src emacs-lisp
;; temporarily stub the shutdown so the countdown can't power off:
(setq cj/ai-term-shutdown-command "echo SHUTDOWN-WOULD-FIRE")
#+end_src
- "wrap it up" in an agent: the valediction renders fully, then that agent's buffer + its =aiv-<proj>= session + the claude process are gone and the window layout is restored.
- "wrap it up with summary" / "and summarize": wrap completes but the buffer stays.
- "wrap it up and shutdown" with a second =aiv-*= session alive: it refuses, names the other session, does a normal wrap (no countdown).
- "wrap it up and shutdown" as the sole session: the echo area counts 10→1 one per second; press C-g mid-count and confirm "Shutdown cancelled."; then let one run to zero and confirm it would fire the (stubbed) command.
#+begin_src emacs-lisp
;; restore the real command when done:
(custom-reevaluate-setting 'cj/ai-term-shutdown-command)
#+end_src
Expected: teardown removes exactly the right session/buffer and restores layout; the with-summary variants keep the buffer; the multi-session shutdown refuses; the sole-session countdown renders, cancels on C-g, and fires only at zero. If any step misbehaves, capture it and reopen. Once the stubbed run looks right, a single real shutdown test confirms the live path.

#+begin_src cj: comment
  I would like to test this in separate steps naturally as I need them across sessions. please add one child task for each item to test above. 
#+end_src

*** 2026-06-15 Mon @ 12:10:06 -0500 org-capture popup single-Task into inbox verified
Craig confirmed: Super+Shift+N pops straight into a Task capture (no menu), single full-frame window, files under "Inbox" in ~/org/roam/inbox.org, and the frame closes cleanly. Passed.
*** 2026-06-11 Thu @ 18:29:39 -0500 Verified UI-face preview and contrast survive a ground bg change
Craig walked the repro: mode-line with its own fg/bg kept its preview bg and ratio through a ground change; ground-dependent rows re-rated; package-faces contrast column updated. Pass. Closed the [#A] contrast-cell and [#B] preview-bg parents.
*** 2026-06-11 Thu @ 18:29:39 -0500 Verified seeded package-face defaults, with steel tuning
Craig read org/magit/elfeed against the ground. Pass with tuning: steel reads a bit dark — flipped to steel+1 on magit (better), but org wanted darker; these are updated selections, NOT final — he expects to adjust many more before the theme ships. His export saved to scripts/theme-studio/theme.json (replaced the 2026-06-09 state, prior version in git at 4f2d00eb). Side find: the org preview's heading-three ↔ headline-todo flash linkage is cross-wired — filed as its own bug task.
*** 2026-06-11 Thu @ 18:29:39 -0500 Verified large face tables stay usable
Craig scrolled the org table, filtered on "agenda", reassigned a face — grouping, narrowing, and live preview update all behaved. Pass.
*** 2026-06-11 Thu @ 18:29:39 -0500 Verified perceptual readouts in the picker
Craig validated the readouts against computed reference values (default fg #f0fef0 on ground #000000: APCA Lc -104.7 / WCAG 20.14; keyword blue #67809c: Lc -33.7 / WCAG 5.14 — negative polarity correct for light-on-dark). Legible, uncrowded. Pass. Side find filed separately: the picker panel itself blends into the page background ([#C] picker-visibility task).
*** 2026-06-11 Thu @ 18:29:39 -0500 Verified ΔE warnings read clearly
Craig built a near-duplicate pair and a well-spread palette: the close pair was named with its ΔE, sorted closest-first with the cap behaving; no warning on the spread palette. Pass.
*** 2026-06-20 Sat @ 22:11:00 -0400 F9 agent toggle no longer shrinks after a C-; b pull-away
Craig confirmed in his live GUI frame: the agent window keeps its height across repeated F9 toggles after a C-; b pull-away, even under the WIP theme's near-zero mode-line-inactive. The total-height capture/replay fix holds (dbee95ae).
*** 2026-06-20 Sat @ 22:11:00 -0400 F9 toggle preserves all windows in a 3-window layout
Craig confirmed in his live GUI frame: toggling the agent off then on in a 3-window layout returns the same three windows — both working windows survive and the agent re-splits its own bottom strip. The reversible-toggle fix holds (64916462).
*** 2026-06-24 Wed @ 00:37:18 -0400 C-<up> copy-mode scroll verified in a real terminal
Craig confirmed in a live terminal: C-<up> enters copy-mode and scrolls up, repeated C-<up> keep scrolling without resetting, the other modified arrows are left alone (C-<left>/C-<right> still do readline word-motion at the prompt). The C-<up>-only fix + already-in-copy guard (commit 7696ff76) holds.
*** DONE theme-studio markdown preview reads like a real README
CLOSED: [2026-06-24 Wed 11:47]
What we're verifying: selecting markdown-mode in the view dropdown shows a realistic README (not the generic face-name list), and the markdown faces render legibly in context. #mdtest already confirms the wiring + that every element's face is real; this is the visual read.
- Reload theme-studio (or make theme-studio-open)
- Pick "markdown-mode" from the view dropdown
Expected: a README preview with headers, bold/italic, code, links, lists/checkboxes, blockquote, table, etc., each in its theme face. Clicking an element flashes its row in the faces table.
*** DONE C-s C-s repeats the last search
CLOSED: [2026-06-24 Wed 11:37]
What we're verifying: the second consecutive C-s repeats the previous consult-line search instead of erroring "No Vertico session". Fix in modules/selection-framework.el (vertico-repeat-save now on minibuffer-setup-hook), live in the daemon.
- Press C-s, type a search term, RET to dismiss (or just narrow then exit)
- Press C-s again, then C-s a second time without any command in between
Expected: the second C-s reopens the last search (vertico-repeat) rather than signalling "No Vertico session".
*** DONE Irreversible actions require a typed "yes" after a daemon restart
CLOSED: [2026-06-24 Wed 11:36]
What we're verifying: the strong-confirm tier is restored for irreversible actions. The global (fset 'yes-or-no-p 'y-or-n-p) was removed and those sites now call cj/confirm-strong, which forces a typed "yes"/"no". The fset is baked into the running daemon and can't be cleared from Lisp, so this only takes effect after a restart. Ordinary yes-or-no-p prompts stay single-key (use-short-answers t).
- Restart the Emacs daemon (clean state)
- Trigger an irreversible action, e.g. M-x cj/system-cmd-shutdown (then abort), or attempt to overwrite a file via the rename/move commands
Expected: the irreversible prompt requires typing the full word "yes" (not a single y); a benign yes-or-no-p prompt elsewhere still accepts a single keystroke.
*** DONE Calibre bookmark default name is "Author, Title"
CLOSED: [2026-06-24 Wed 10:56]
What we're verifying: a new nov bookmark takes the "Author, Title" form parsed from the filename, not the raw EPUB filename.
- Open an EPUB in Calibre (nov buffer).
- Hit m to set a bookmark.
Expected: the default bookmark name is "Author, Title" (underscores stripped, colon restored), e.g. "Agatha Christie, The A.B.C. Murders".

*** DONE theme-studio gnus view package themes the article headers
CLOSED: [2026-06-24 Wed 11:29]
What we're verifying: gnus is now its own view package in theme-studio (it drives the mu4e article view), so the bright-green article headers can be themed and exported. #gnustest confirms the package is registered and its preview emits only real gnus faces; this is the visual read plus the live-green retirement.
- Reload theme-studio (or make theme-studio-open)
- Pick "gnus (mu4e article view)" from the view dropdown (sits among the g entries)
- Confirm the preview shows a header block, an emphasized body, an 11-level quoted reply chain, and a signature
- Theme a few gnus faces (e.g. gnus-header-name, gnus-header-from, gnus-cite-1) to obvious colors, export to WIP.json, then deploy
#+begin_src sh :results output
make -C /home/cjennings/.emacs.d deploy-wip
#+end_src
- Restart Emacs (or reload the theme), reopen a mu4e message
Expected: the studio preview renders each gnus face in its theme color; after export + deploy, the *mu4e-article* From/Subject/To/Date headers show the themed colors instead of the gnus green defaults.
*** DONE dashboard theming — banner gold, headings themed, items show per-filetype icons
CLOSED: [2026-06-24 Wed 11:29]
What we're verifying: with the dashboard out of global font-lock (Fix A) and file icons on (Fix C), the live dashboard shows the theme colors and icons. Eyeball it.
- Open the dashboard (F1)
Expected: the "Emacs:" banner title is gold, the "Projects:/Bookmarks:/Recent Files:" headings are themed blue, and the project/recent-file rows each show a colored per-filetype icon (org files greenish, dirs yellow; bookmarks a plain icon).
*** DONE info-mode open is non-destructive and cancels cleanly
CLOSED: [2026-06-24 Wed 11:41]
What we're verifying: opening a .info file no longer auto-kills the buffer, and the explicit cj/open-with-info-mode prompt cancels cleanly on decline. Fixed in modules/help-config.el; stale daemon state already cleared, so this also survives a fresh restart.
- find-file a .info file (e.g. one under elpa) — it should open as an ordinary buffer, not vanish into Info
- In that buffer, edit something, then M-x cj/open-with-info-mode; at the save prompt answer no
- Repeat M-x cj/open-with-info-mode on an unmodified .info buffer
Expected: find-file leaves the buffer intact (no auto-kill); declining the save prompt prints "Operation canceled" with no "No catch for tag" error; on an unmodified buffer it opens the file in Info.
*** DONE C-; b d diffs, C-; b D deletes
CLOSED: [2026-06-24 Wed 11:43]
What we're verifying: the buffer-and-file keymap now puts diff on the easy lowercase key and the destructive delete on the capital. Swapped in modules/custom-buffer-file.el and re-bound live in the daemon.
- Open a file buffer and edit it without saving
- Press C-; b d
- Press C-; b D, then cancel at the delete confirmation
Expected: C-; b d runs the diff (buffer vs saved file); C-; b D starts delete-buffer-and-file (offers to delete the file). Before the swap these were reversed.
*** DONE nerd-icons colors are theme-driven (legend + live icons)
CLOSED: [2026-06-24 Wed 11:35]
What we're verifying: the nerd-icons v1 feature reads right end to end. The Python/Node/browser gates pass; this is the visual confirmation the gates can't make — the legend pane and the real per-filetype icon colors after the tint removal.
- In theme-studio, open the nerd-icons pane: the legend should show each filetype's real nerd-font glyph in its mapped color (el purple, py dark-blue, dir yellow, …), with the 34 color faces editable on the left.
- Recolor a face (e.g. nerd-icons-purple) and confirm every legend row mapped to it repaints immediately.
- Restart Emacs (the running daemon still has the old darkgoldenrod tint baked into the faces until restart).
- In a fresh frame, look at icons in completing-read (find-file), dirvish, the dashboard, and ibuffer.
Expected: the legend renders glyphs in their assigned colors and recolor repaints live; after restart, file/dir/buffer icons show nerd-icons' per-filetype multicolor palette driven by the theme (not a uniform darkgoldenrod), and directory icons are yellow. If icons are still uniform or uncolored, capture it and reopen.
*** DONE ai-term keybindings land on C-; a + M-SPC
CLOSED: [2026-06-24 Wed 10:36]
What we're verifying: the relocated ai-term keys work in a live frame, including from inside an agent buffer, and the no-agent fallback launches the picker.
- Press M-SPC from a normal buffer with at least one agent open.
- Press M-SPC again from inside an agent buffer (ghostel).
- With no agent running, press M-SPC.
- Walk C-; a a, C-; a s, C-; a n, C-; a k (which-key should show the ai-term menu under C-; a).
- Press F9, C-F9, s-F9, M-F9.
Expected: M-SPC swaps to the next agent (rotating, wrapping) both from a normal buffer and from inside an agent. With no agent running, M-SPC opens the project picker rather than erroring. C-; a a toggles the most-recent agent, s opens the picker, n swaps, k closes. The F9 family does nothing (unbound). Note: the running daemon still has gptel in memory from before the archive, so a full Emacs restart is the clean confirmation that nothing regressed at startup.
*** DONE deferred game commands still work after a restart (load-graph Phase 4)
CLOSED: [2026-06-24 Wed 10:37]
What we're verifying: with games-config no longer eagerly required, malyon and 2048-game still launch from a fresh Emacs, and games-config loads on first use rather than at startup. Batch tests cover the autoload chain; this is the interactive confirmation the spec asks for after each deferral batch.
- Restart Emacs (daemon or standalone) so games-config is no longer pre-loaded from this session.
- Confirm it's not loaded at startup:
#+begin_src emacs-lisp
(featurep 'games-config)
#+end_src
- M-x malyon — it should load games-config and the malyon package, then start interactive fiction (stories under ~/sync/org/text.games/).
- M-x 2048-game — should start the 2048 puzzle.
- Re-check (featurep 'games-config) — now non-nil.
Expected: at startup (featurep 'games-config) is nil; both commands launch normally; after invoking one, games-config is loaded. If a command errors instead of launching, capture it and reopen the deferral as a TODO.
*** DONE native-comp + gcmh survive a daemon restart cleanly
CLOSED: [2026-06-24 Wed 10:37]
What we're verifying: re-enabling JIT native compilation and switching GC to gcmh holds up across a full daemon restart and a real work session. The fix is live in the current daemon and a throwaway daemon launched clean, but the already-loaded modules only get natively compiled on a fresh start (a background async burst), and the old "Selecting deleted buffer" race needs a real GUI session to rule out on 30.2.
- Restart the Emacs daemon (clean state): kill it and start fresh, or reboot.
- Use Emacs normally for a while — the first session after restart triggers background native compilation of ~100 modules. Watch for any "Selecting deleted buffer" errors or compilation crashes (check the *Async-native-compile-log* buffer and comp-warnings.log).
- After things settle, confirm the settings are live:
#+begin_src emacs-lisp
(list :jit native-comp-jit-compilation
      :gcmh gcmh-mode
      :gcmh-high gcmh-high-cons-threshold)
#+end_src
- Edit normally (completion, agenda, AI buffers) and notice whether the periodic GC jank is gone.
Expected: restart is clean (no backtrace); the background native-comp burst finishes without "Selecting deleted buffer" errors; the form returns (:jit t :gcmh t :gcmh-high 1073741824); editing feels smoother with no frequent GC pauses. If the async race recurs on 30.2, capture the error and reopen as a TODO — the fallback is an AOT sweep or going back to JIT-off.
*** DONE mu4e buffers are themed (headers, main, message view)
CLOSED: [2026-06-24 Wed 10:38]
What we're verifying: with the mu4e modes excluded from global font-lock, mu4e's manual face properties survive, so the buffers pick up the theme. The headers + main + view-headers are the ones global font-lock was stripping.
- Restart Emacs (cleanest), or kill and reopen the mu4e buffers
- Open mu4e, look at the headers list and the main menu
- Open a message and read the body
Expected: headers list shows unread/flagged/date/subject in their theme colors (mu4e-unread-face gold, mu4e-header-face green, etc.); the main menu and the message-view headers (From/To/Subject) are themed; the message body still renders correctly (gnus does the body, so it's unaffected). NOTE: a plain "g" refresh in an already-open *mu4e-headers* won't fix it on its own unless font-lock is off there; a restart is the reliable check.
*** DONE slack keys are safe before slack loads
CLOSED: [2026-06-24 Wed 10:44]
What we're verifying: the C-; S slack keys don't error before slack has started, and the prefix shows in which-key. Fixed in modules/slack-config.el; restart to apply (not reloaded into the live session).
- Restart Emacs but do NOT run cj/slack-start
- Press C-; S Q (close all), and C-; S w / @ / # (these previously void-function'd or void-variable'd before load)
- Press C-; S and check which-key shows the "slack" prefix
Expected: C-; S Q reports "Closed 0 Slack buffers" with no error; w/@/# either run or autoload slack cleanly (no void-function); the which-key popup lists the slack prefix.
*** DONE modeline still shows the git branch and state
CLOSED: [2026-06-24 Wed 10:45]
What we're verifying: the VC-cache simplification didn't change what the modeline shows on a normal repo. Fixed in modules/modeline-config.el (live in the daemon after reload).
- Open a file inside a git repo
- Glance at the mode-line VC segment
Expected: the branch name and state still render as before (e.g. "main" with the usual state face). The change only drops a per-render stat and guards against git errors; normal display is unchanged.

*** DONE Lock screen actually locks on Wayland
CLOSED: [2026-06-24 Wed 10:45]
What we're verifying: C-; ! l locks the screen on Wayland. slock (X11-only) never worked here; the locker now runs loginctl lock-session, which logind turns into a Lock signal that hypridle handles by running hyprlock — the same path idle/sleep locking already uses. Fix in modules/system-commands.el, live in the daemon.
- Press C-; ! l (or run M-x cj/system-cmd-lock)
- The screen should lock with hyprlock
- Unlock with your password
Expected: the screen locks immediately and unlocks with your password. (Before the fix it printed "Running lockscreen-cmd..." and nothing happened.)
*** DONE OKLCH editor feels right
CLOSED: [2026-06-24 Wed 10:47]
What we're verifying: the OKLCH sliders / C×L plane edit cleanly and clamping is visible.
- Switch the picker to OKLCH mode and drag L, then C, then H
- Push chroma past the sRGB gamut, then toggle the AA/AAA mask
Expected: each axis moves independently; the C×L plane (once 4b lands) opens on the current color; "chroma clamped to sRGB" shows on clamp; toggling the mask does not reset OKLCH mode.
*** DONE Generated ramp harmonizes
CLOSED: [2026-06-24 Wed 10:47]
What we're verifying: a ramp generated from a base color reads as one family, not a grab-bag (the aesthetic the math is meant to produce).
- Open =scripts/theme-studio/theme-studio.html= in Chrome
- Pick a mid-lightness base swatch (e.g. a blue) and generate its ramp at the defaults
- Read the row of steps left to right, then try a near-black and a near-white base
Expected: the steps share an obvious hue and step evenly in lightness; the chroma-ease keeps the extreme steps from going muddy or garish; nothing looks like it belongs to a different color.
*** DONE Color families group the way the eye reads them
CLOSED: [2026-06-24 Wed 10:51]
What we're verifying: the OKLCH hue clustering (25° gap) splits and merges families the way you'd expect, and renaming never moves a color.
- Open =scripts/theme-studio/theme-studio.html= in Chrome and load a real theme (e.g. sterling)
- Read the strips top to bottom: are "the blues" one strip, "the greens" another, neutrals and ground pinned at the top
- Find a pair you'd consider one family that landed in two strips (or two you'd consider separate that merged)
- Rename any swatch to something absurd and confirm it stays in the same strip
Expected: families match your mental grouping; the few that don't are the cue to revisit the 25° gap; renaming never regroups.
*** DONE Removed-step references read clearly as "(gone)"
CLOSED: [2026-06-24 Wed 10:46]
What we're verifying: lowering a family's count leaves a referencing face visibly stale, not silently re-pointed.
- Assign a UI or syntax element to an outer step of a family (e.g. region = a blue+3)
- Lower that family's count to 2 so blue+3 disappears
- Read the assignment's dropdown
Expected: the dropdown shows "(gone)" for the removed step, never a silent jump to a different color; re-pointing it is a deliberate choice.
*** DONE Dirvish d duplicates, D force-deletes with a confirm
CLOSED: [2026-06-24 Wed 10:52]
What we're verifying: in dirvish, d now duplicates the file at point (delete-to-trash removed), and D force-deletes the marked files via sudo rm -rf after a yes-or-no-p naming the targets. The pure command builder is unit-tested; this is the live keypress plus the guarded destructive path.
- Open dirvish on a scratch directory holding a couple of throwaway files
- Put point on a file and press d — confirm a "<name>-copy.<ext>" appears (a duplicate, nothing deleted)
- Mark one or two throwaway files, press D, and read the "Force-delete (sudo rm -rf, NO undo): <names>?" prompt
- Answer no first (confirm nothing happens), then press D again and answer yes
- Note whether sudo prompts for a password and whether the file actually disappears
Expected: d duplicates; D names the exact targets and only deletes on yes; the files are gone with no trash copy. If sudo needs a password that shell-command can't supply, flag it — the delete may need to route through a tty instead.
** PROJECT [#A] Theme-Studio Open Work
Parent grouping the open theme-studio / theming issues; close each child independently.
*** TODO [#C] theme-studio: surface font-lock faces in the studio :bug:studio:
font-lock faces (keyword / string / comment / type / ...) are present in the inventory — they live in =emacs-default-faces.json= and the theme files (e.g. =distinguished.json=, =theme.json=), not =package-inventory.json=. So the data is there; the open question is why they don't appear in the studio pane. Investigate the studio UI's view/group assignment for core syntax faces and surface them where expected (or report that they already are, and where). From the roam inbox.
*** TODO [#C] theme-studio: contrast calc should account for distant-foreground :feature:studio:
The studio's contrast numbers ignore Emacs's distant-foreground swap — the color Emacs substitutes when fg/bg are too close. First document Emacs's algorithm (when the swap kicks in and how the threshold is computed), then find the fg/bg combination with the least contrast under that rule and report contrast against that worst case, not just the nominal fg. From the roam inbox.
*** TODO [#C] theme-studio: flag a face inheriting from itself as a mistake :feature:studio:
A face set to inherit from itself renders unexpectedly. When a face's inherit dropdown selects itself, mark it as an error: outline the dropdown (or zebra-stripe it — pick during build) with a terse tooltip describing the problem. Still allow saving (warning, not a block). Also identify other similar self-referential / invalid-combination error cases and apply the same warning pattern. From the roam inbox.
*** TODO [#C] theme-studio: live preview should outline the auto-dim text, not the normal text :bug:studio:
The live-preview outline currently marks the normal-theme text; it should outline the auto-dim variant instead. From the roam inbox.
*** 2026-06-28 Sun @ 06:53:32 -0400 wttrin captured in the studio inventory (4 faces)
Root cause was the inventory regex (fixed in a5fd0b4d): it only captured =/elpa/PKG-VERSION/= dirs, excluding wttrin's unversioned =/elpa/wttrin/= checkout. Confirmed on a clean wttrin load that =symbol-file= attributes its faces to =/elpa/wttrin/wttrin.elc= correctly. The live daemon's wttrin attribution was disturbed by the session's theme reloading (=symbol-file= returns nil; reload + unload-feature didn't repair it), so I did NOT regenerate the whole inventory from the daemon (that would have lost attribution for other packages too). Instead, surgically added wttrin's four file-loaded faces (=wttrin-instructions=, =wttrin-key=, =wttrin-mode-line-stale=, =wttrin-staleness-header=) to =package-inventory.json= from a clean batch load, regenerated =theme-studio.html= (make gen), and confirmed all studio gates green. wttrin is now a generic-preview app in the dropdown.
Two residuals, neither blocking: (a) the OTHER local-checkout packages the regex fix unblocks are not yet captured — that needs one full inventory regen in a freshly-restarted (clean) daemon, best run after Craig's next Emacs restart; (b) =wttrin-instructions-header= is eval-defined outside the checkout (the checkout defines =wttrin-instructions=, not =-instructions-header=), so it can't be captured here — it would need to land in =elpa/wttrin/wttrin.el=. Optional polish: a bespoke two-column-footer =renderWttrin= instead of the generic preview. Visual confirm filed under "Manual testing and validation".
*** 2026-06-27 Sat @ 22:05:31 -0400 Rebuilt the dirvish preview as a realistic two-pane
Shipped in 61b68fcf (option 2). Two-pane dirvish: an active listing (per-type nerd-icons, sizes, hl-line, dimmed backup) beside an =ls -l= preview pane, the remaining faces in a labeled extras strip, all 38 dirvish faces still covered. Visual verified via off-screen screenshot.
*** TODO [#A] theme-studio: consistent assignment-view table columns :feature:studio:next:
All view-assignment tables should use one consistent column set and order, whatever view is selected: element name (sortable), lock, fg, bg, style, box (with a side expansion showing the selected color, as in UI faces), contrast, inheritance, size, preview text. No other columns at this design stage. When a view's elements can't take a given section, raise a signal and disable that section for that view; the disabled state is the visual cue. From the roam inbox 2026-06-16.
*** VERIFY [#A] theme-studio: deploy-wip button on the browser page :feature:studio:next:
Needs from Craig: a mechanism choice before I build it. The page is served from file://, so a button can't run make directly. Two options: (a) a tiny localhost helper the page POSTs to (it runs make deploy-wip), or (b) the page writes a watched trigger file that a small daemon/timer picks up. Pick (a) or (b) and I'll implement + test it.
Add a button on the theme-studio page that runs the make deploy-wip target locally (build WIP.json into the theme, live-reload the daemon). The page is served from file://, so the browser can't run make directly. Needs a local bridge: a tiny localhost helper the button POSTs to, or a watched trigger file the page writes. Pick the mechanism before building. From the roam inbox 2026-06-15.
*** VERIFY [#A] theme-studio: cannot reassign fg color      :bug:studio:next:
Needs from Craig: the exact repro (palette JSON + click sequence, or a quick screen capture). I traced it and couldn't reproduce from the code: updateColor (the "update selected" path) already excludes the selected entry from its uniqueness check (j!==i), and the fg/bg chips are selectable — paletteChip wires d.onclick -> selectColor(i), with the lock only blocking removal, not selection. The "already exists" wording is addColor's message, which is only reached via applyEdit when selectedIdx is null (i.e. no chip selected). So the trigger is a state I can't see statically — selection getting lost before "update", or a second entry already named "fg". With the precise steps I can pin it; I won't guess-patch the palette-update path on an [#A] bug since a wrong fix there corrupts themes.
Selecting the fg tile, changing its value, and clicking update errors that an fg already exists instead of updating it. The update path treats a reassign as an add. From the roam inbox.
*** DOING [#B] Route hardcoded theme colors through the theme :refactor:studio:
Phase 1 DONE (2026-06-25, commit 439fb0e6): stripped every literal color from the config modules so nothing assigns a non-themeable value (0 hex + no named-color face values remain; validate-modules + org-faces/build-theme/face-diagnostic tests clean). The config now renders with default/theme faces, which surfaces where theming support is missing. *Restart Emacs to see the bare state* — the running daemon still holds some accumulated colored state (e.g. =hl-todo-keyword-faces=) that only clears on restart.

Phase 2 — gaps to surface as themeable faces (exploration; work as we decide what to do):
- *hl-todo keyword colors* (=prog-general.el=): removed the literal FIXME/BUG/HACK/ISSUE/TASK/NOTE/WIP colors; it now falls to hl-todo's package defaults. Add themeable faces (or route FIXME/BUG/HACK -> =error=, ISSUE/TASK -> =warning=, NOTE -> =success=, and a new info-blue for WIP).
- *eshell prompt* (=eshell-config.el=): the timestamp/user/host/pwd were "gray" and the =%= was "white"; now the default face. Add themeable prompt faces (or route to =shadow= / =eshell-prompt=).
- *active-window bg tint* (=org-noter-config.el=, =music-config.el=): the =#1d1b19= tint is gone (the =face-remap-add-relative= is now a no-op); the active window uses the default bg. Needs a themeable "active-buffer tint" face if the distinction is wanted back — same shape as the removed =*scratch*= tint.
- *pdf reading colors* (=pdf-config.el=): =pdf-view-midnight-colors= removed; pdf-tools' own default applies. Needs themeable midnight fg/bg.
- *epub/nov reading color* (=calibredb-epub-config.el=): the =#E8DCC0= sepia removed; reading fg falls to the default. Needs a themeable reading face.
- *org-faces defface defaults* (=org-faces-config.el=): the ~28 literal defaults were stripped. The theme overrides these at runtime, so the focused faces stay themed — but confirm the theme covers the =-dim= variants (auto-dim's non-selected-window faces) too, else those render bare.
From the 2026-06-16 audit; exploration phase 2026-06-25. The nerd-icons "darkgoldenrod" tint from the original audit is already gone.
*** VERIFY [#B] theme-studio: sort newest colors near the top :feature:studio:next:
Deferred from the no-approvals batch (no blocker, needs a focused studio session). Plan: the palette + gallery order comes from columnsFromPalette / sortColumns / paletteOptionList; newest entries currently sort low. Add a recency signal (palette insertion order) and surface recent columns near the front. Risk: the column sort is pinned by several browser gates (#sorttest etc.), so it needs careful test updates — which is why I held it rather than rush it here.
Newly added colors currently land after the ground layer (bg/fg), low in the order. Surface them near the first entry instead, in both the palette color list and the gallery/dropdown, since the most recently added colors are usually the ones being worked on. From the roam inbox 2026-06-15.
*** 2026-06-25 Thu @ 13:58:07 -0400 theme-studio dashboard preview: icons render, items themeable
Both halves resolved. Icon/mojibake half: the decision (embed the nerd font) was made and shipped during the gallery work — a Symbols Nerd Font is @font-face'd into the studio page (=ThemeStudioNerd= in styles.css / previews.js), so the dashboard preview's navigator renders real glyphs instead of mojibake. Items half: =dashboard-items-face= is now an editable face (=face_data.py= DASHBOARD_FACES), and the preview's project/bookmark/recent rows are wrapped in =dashboard-items-face= (commit 1303d995), so editing it recolors them. It inherits =widget-button= (default) while unset, so the rows stay bare during the vanilla exploration until the face is themed.
*** TODO [#B] theme-studio import organization workflow needs a spec :feature:studio:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
Design import handling for unstructured color sources such as Emacs themes, CSS palettes, screenshots, and generic palette files. Principles from the 2026-06-13 Theme Studio discussion:
- Preserve declared structure whenever an imported entry has a =columnId=.
- For unstructured legacy imports with no =columnId=, avoid silent hue clustering and avoid treating arbitrary =color-N= names as one long ramp; each =color-N= should become its own base column.
- Keep meaningful generated ramp-name inference for names like =blue-1= / =blue= / =blue+1=.
- Group external numeric color-name variants for compact display: =blue1= / =blue2= / =blue3= infer column =blue=; =grey80= / =grey81= infer column =grey=; =orchid3= infers =orchid=. This is display organization, not proof that the colors are an authored Theme Studio span.
- If a numeric external base is spanned later, generate from the actual base name, e.g. =blue1-1= / =blue1= / =blue1+1=, while keeping those generated tiles in the inferred =blue= column.
- Add explicit organization tools rather than hidden inference: group selected colors into a column, suggest hue groups as a preview/action, sort imported colors for inspection, and promote a color from an import bucket into a normal column.
- Consider a compact imported/captured bucket UI for large unstructured imports while preserving per-color column ids internally.

*** VERIFY [#B] theme-studio: org-agenda app + agenda preview :feature:theme-studio: :studio:next:
Needs from Craig: this is a multi-phase feature, not a bug fix — it depends on the preview-locate feature (per the 2026-06-15 spec) and means breaking org-agenda-* / scheduling / deadline / calendar / clocking faces into their own theme-studio pane with a representative week-agenda preview. Too large to land inside this batch. Confirm you want it built now (and as its own focused session) and I'll start from the spec; otherwise it stays parked.
Break the org-agenda-* plus scheduling / deadline / calendar / clocking / filter faces out of the overloaded org-mode app into a dedicated org-agenda pane (org-mode-line-clock* stay in org-mode), with a representative week-agenda preview at natural item frequency. Keywords, priorities, and tags render live via org-faces / org-mode through the locate registry (hover-only there). Same five-file bespoke-app pattern as org-faces. Depends on the preview-locate feature. Partly subsumes the "break org-mode preview into grouped subsections" task.
*** TODO [#B] theme-studio UI face inheritance needs a spec  :feature:studio:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
Package faces model =inherit= explicitly, but UI faces currently expose only fg/bg/style fields in the table and generated theme output. Before implementing UI-face inheritance, write and review a small spec that defines: which UI faces get an inherit selector, how own defaults from =emacs-default-faces.json= appear versus effective inherited values, how export/import stores cleared vs inherited vs explicit values, how preview resolution follows UI inherit chains, and what browser gates prove the behavior. This touches the UI model, generated defaults, export format, preview rendering, and reset semantics, so it should not be slipped in as a refactor.

*** 2026-06-25 Thu @ 15:29:51 -0400 Dashboard theming fixed: font-lock, file + heading icons, items themeable
All three causes resolved. Cause A (font-lock stripping faces) fixed 2026-06-16 (202cf430). Cause C: file icons fixed 2026-06-16 (1c97cba7), and section-heading icons now enabled too (=dashboard-set-heading-icons t=, 2026-06-25). Cause B (item color) unblocked — theme-studio now exposes =dashboard-items-face= (=face_data.py=) so the items are colored from the theme, not a hardcoded hex; setting that color is the studio's job now. Original diagnosis (2026-06-16, live daemon inspection) kept below.

**** Cause A — banner + section headings render default ("Banner Text not gold")
=global-font-lock-mode= (enabled at startup, =early-init.el:311=) fontifies the =*dashboard*= buffer. Dashboard applies the banner title (=dashboard-banner-logo-title=) and section headings (=dashboard-heading=) via the =face= TEXT PROPERTY. font-lock owns the =face= property and strips manually-applied ones it didn't set via keywords, so those faces get cleared on render (every line carries =fontified t=, the jit-lock fingerprint). The theme is fine: =dashboard-banner-logo-title= computes to #dab53d gold and =dashboard-heading= to #67809c — they're stripped at render, not missing. This is a regression of the 2026-05-22 fix "Dashboard navigator icons and section titles uncolored" (7496), which worked before font-lock ran in this buffer.
FIX A — DONE 2026-06-16, commit =202cf430=: exclude dashboard-mode from global font-lock — =(setq font-lock-global-modes '(not dashboard-mode))= at top level in =dashboard-config.el= (top-level so it runs even though the use-package =:config= errors on a void nerd-icons symbol under the test harness). Banner is gold again and the headings pick up =dashboard-heading=. TDD test =tests/test-dashboard-config-font-lock.el=; full suite green; live in the daemon. Causes B and C still open below.

**** Cause B — project/bookmark/recent items have no color
Items and the navigator are painted by a =dashboard-items-face= button OVERLAY (overlays survive font-lock, which is why Cause A didn't touch them). But in =WIP-theme.el= =dashboard-items-face= is just =(:inherit widget-button)= — unspecified foreground, so it renders in the default color. 7496 had colored it (steel+2) in the now-retired Dupre theme; that color never carried into WIP. Per 7496, the navigator and items share =dashboard-items-face=, so coloring it colors both (separating them is the open task "Color dashboard navigator independently of list items", 7740).
FIX B (per Craig 2026-06-16 — no hardcoded colors, theme it): the items already fall back to the default foreground (=dashboard-items-face= inherits =widget-button= -> unspecified -> default fg), which is the right default. To actually COLOR them, theme-studio must expose =dashboard-items-face= so the color comes from the theme, not a hardcoded hex in =WIP-theme.el=. That is the items half of task 2418. No config/theme change here; this routes to 2418.

**** Cause C — no icons on items or section titles
=dashboard-set-file-icons= and =dashboard-set-heading-icons= are both nil in the live config (=dashboard-config.el= sets =dashboard-display-icons-p t= + =dashboard-icon-type 'nerd-icons= but never the two enable toggles), so dashboard renders no file/section icons. Only the custom navigator row has icons.
FIX C — file icons DONE 2026-06-16, commit =1c97cba7=: =(setq dashboard-set-file-icons t)= in =dashboard-config.el=. Items now show nerd-icons file icons colored per filetype (verified live: =todo.org= -> nerd-icons-lgreen, project dirs -> nerd-icons-yellow; bookmarks fall back to a generic uncolored icon, no filetype to map). Per Craig: per-filetype (the nerd-icons default). They render only because Fix A took the dashboard out of font-lock, which was stripping the icon faces too. OPEN (offered, not done): =dashboard-set-heading-icons t= would add icons to the section titles — left off pending Craig's call.

**** Studio angle
To set the item color from theme-studio instead of hand-editing =WIP-theme.el=, the studio's dashboard app must expose =dashboard-items-face= as editable — the "list items unthemed" half of task 2418 (theme-studio: dashboard preview icons missing, list items unthemed).

**** Next
Confirm Fix A to persist it; pick the item color (Fix B); decide the icon enable + color policy (Fix C).
*** TODO [#B] theme-studio semantic theme architecture :feature:theme-studio:spec: :spec:studio:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-14
:END:
Spec draft: [[id:fe980b12-451a-4d8b-a550-d99f9ec49f45][theme-studio-semantic-theme-architecture-spec.org]].

Design a Modus-inspired layered Theme Studio output path: palette data, semantic role mappings, face templates, and a generated theme wrapper. Keep the current flat JSON-to-theme converter as the compatibility/default path while proving a layered, self-contained generated theme. Include advisory semantic rules as a possible validation layer, not v1 enforcement.

**** TODO [#B] theme-studio palette generator source modes for base-only vs ground-aware palettes :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-14
:END:
Tentative follow-up from walking through the generator algorithms. Consider splitting the current =source: palette= behavior into two explicit source modes, names TBD:
- =base color palette= — current behavior; use non-ground base color columns only and ignore bg, fg, ground spans, and color spans.
- =ground and base palette= — use bg/fg plus non-ground base color columns as generator anchors, useful when colored ground endpoints should shape fill-gap or harmony choices.

This may be cancelled if the extra distinction makes the generator harder to understand. Before implementing, decide final names and whether ground-aware source should include only bg/fg or also ground span steps.

*** TODO [#B] theme-studio seeding engine :feature:studio:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
Spec (Ready): [[id:b70b37f2-37df-4c8e-ac2f-1f20d12e33dd][spec]]. Role table → guide-correct defaults for syntax/UI/org; reseed dupre-revised.json to the compact mapping; opens seeded with an all-tier reseed button. Depends on the perceptual-metrics colormath.js core for OKLCH shade generation, so it runs after that feature's Phase 1.
**** TODO Seed model + seed() + #seedtest :solo:
Phase 1. Palette anchors + OKLCH shade generation (reusing colormath.js), the ROLES table, and the three face→role maps as data; pure seed(). Gate: #seedtest asserts representative syntax/UI/org faces resolve correctly (bi→blue-grey, fnd→gold+bold, region bg-only, link underlined, org-level-1 strongest, org-code literal lane) and a non-org bespoke package (magit) keeps its curated seed.
**** TODO Open-seeded + reseed + dupre-revised regen :solo:
Phase 2. Initial state from seed() plus seedPkgmap for the non-org packages; all-tier reseed button with a scope-named overwrite warning, resetting non-org to their APPS defaults; regenerate dupre-revised.json. Gate: #selftest PASS; default-on-open equals seed(); artifact round-trip (regenerated dupre-revised.json imports back to the same seeded state); Chrome eyeball.
**** TODO Seeding-engine test surface :solo:test:
Keep #seedtest, #selftest, the default-on-open check, the dupre-revised round-trip, node --check, and Chrome validation green.
*** TODO [#C] ansi-color dropdown plain, reuse info in the hover :feature:studio:
Drop the parenthetical from the "ansi color" assignment-view dropdown label so it reads plain, and move the explanation to the hover instead: name the packages that reuse these colors (vterm / eshell / compilation / ghostel) and verify they actually do before stating it. From the roam inbox 2026-06-24.
*** TODO [#C] theme-studio: custom view-assignment dropdown with lock indicators :feature:studio:next:
The view-assignment dropdown is a plain HTML menu. Make it a custom menu colored like the other custom menus, and have it indicate which assignment views have all their elements locked, so the user knows when a view's assignments are done. From the roam inbox 2026-06-16.
*** TODO [#C] theme-studio: calibre package doesn't color properly :bug:studio:
The calibre package preview has no elements to theme in the search list, and coloring switches to the string color on mismatched quotes. Investigate, then record a diagnosis and solution in this task before fixing. From the roam inbox 2026-06-15.
*** TODO [#C] theme-studio: break org-mode preview into grouped subsections :feature:studio:
Rather than cramming all org-mode preview into one pane, split into groups so each element is shown in a common, context-rich environment. From the roam inbox.
*** TODO [#C] theme-studio: elfeed ignores theme assignments  :studio:studio:
The preview shows theme colors, but elfeed itself renders all-white with no variation. Note: this may be the shr-rendered entry/article view (elfeed-show), where color often comes from the document rather than the theme — confirm whether the symptom is in the search list or the article view. From the roam inbox.
*** VERIFY [#C] theme-studio face-consistency check     :feature:studio:next:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-10
:END:
Needs from Craig: this is an open-ended feature, not a bug — it needs a spec first (what "consistency" means: which faces are compared, what rule flags an inconsistency, how it's surfaced in the UI). Give me the check's definition (or say "brainstorm a spec") and I'll build it; parked until then.
Rule taxonomy captured in [[file:docs/design/theme-studio-face-rules.org][docs/design/theme-studio-face-rules.org]] (Design Rules vs Fidelity Rules). The two checks below map to those two rule kinds. Both surface structural-attribute (weight/slant/underline/box/overline/height) issues; color is the theme's design and out of scope.

1. Theme cross-cutting consistency (primary, per Craig 2026-06-09): the theme has deliberate cross-cutting rules — e.g. headings/titles are bold, links are underlined, errors/warnings/success are bold. Flag where the theme BREAKS ITS OWN rule (a heading that isn't bold, a link that isn't underlined). The designer declares the rules; the check finds the violators. This is the "tell me where I broke the rule" guardrail.

2. defface-baseline divergence (secondary): flag where a face's structural attrs differ from its package =defface= so each divergence is deliberate, not an accidental drop. Would have caught the dropped underline/bold defaults and the contradictions (shr-h3 bold-vs-italic, erc-action italic-vs-bold) from the package-face audit as they were introduced.

Bake into the tool (a lint surfaced in the UI) or run as a build-time check (seeds vs live deffaces via emacsclient).

*** TODO [#C] theme-studio: restrict the cursor row to its background :bug:studio:
The UI table gives the cursor face the full control set (fg, B/I/U/S, box), but Emacs only honors the cursor face's :background. Its shape is cursor-type, not a face attribute, so every other control on that row is a no-op once the theme loads. Restrict the cursor row to just its background swatch so the studio doesn't present controls Emacs drops.
*** TODO [#C] theme-studio terminal/ANSI colors              :feature:studio:
theme-studio represents GUI faces only; terminal colors aren't surfaced at all. Scope decided 2026-06-09: GUI-first faces, NOT full per-face display-class fallback. Two pieces:

1. ANSI-16 panel. Map the 16 ANSI slots (black/red/green/yellow/blue/magenta/cyan/white + bright variants) to palette colors, with a preview, and export them so =build-theme.el= emits the =ansi-color-*= / =term-color-*= faces. This matters even in pure-GUI Emacs: colored shell output, compilation buffers, eshell, and vterm/eat all draw from these. Signals must line up with their ANSI slot (error red→ansi red, success→green, warning→yellow, info/link→blue) so a signal reads the same in a terminal.

2. Core-face 16-color fallback. Only the ~10 faces that decide console legibility get a =(((class color) (min-colors 16)) ...)= clause plus a =(t ...)= floor: default/fg, bg, keyword, string, comment, constant, error, warning, region, mode-line, line-number. Tune these for contrast — push it UP, legibility over fidelity, because the only 16-color target is the bare Linux virtual console (an occasional emergency context). The long tail stays GUI-first and auto-approximates.

Why this scope: the GUI and the normal terminal (foot + tmux, truecolor / ≥256-color) both render the GUI hexes fine; GUI-first is correct there. Only the Linux VT is 16-color, and a low-contrast palette approximates badly down to 16 — so a few core faces get a deliberately higher-contrast 16-color fallback rather than every face carrying a multi-spec. Tool work: the ANSI-16 panel + a flag on the core faces to also capture a 16-color value; =build-theme.el= emits multi-spec only for those. Full per-face fallback is revisited only if console work becomes regular.
*** VERIFY [#C] Palette-columns spec review
SCHEDULED: <2026-06-12 Fri>
Read [[file:docs/theme-studio-palette-columns-spec.org][docs/theme-studio-palette-columns-spec.org]] (Draft, from the 2026-06-10 design discussion) and bless or amend. Decisions 9 and 10 are the two session calls awaiting your word: strips flip to lightest→darkest top→bottom to match the dropdown, and each dropdown column run places the base at its natural lightness position (vs bg/fg bases leading before any steps). On "spec's good": mark Ready, file the phase breakdown, cancel the [#C] hint-override task, start Phase 1.

*** 2026-06-24 Wed @ 21:53:39 -0400 Editable face-list color grouping cancelled — subsumed by the gallery
The roam-inbox ask was to default-group the editable nerd-icons face table by color family. Craig's call (2026-06-24): the gallery preview already clusters the icons by hue, which covers the underlying "see colors grouped" need, so grouping the 34-row editable table too isn't worth it. Cancelled.
*** 2026-06-24 Wed @ 18:09:26 -0400 theme-studio tier-1 simplifications landed
Behavior-preserving simplifications from the four-agent refactor/simplify assessment, all test-verified (full suite green). Landed: syncMockHeight + syncPkgHeight merged into syncPaneHeight(tableId, paneId); the dead generatorHues "manual" branch deleted (identical to fallback); locateInfoLine removed (fn + export + test, orphaned this session); the redundant pkgbody guard dropped (buildPkgTable self-guards); displayHex/displayName closures inlined; paintUI now calls worstCellHtml; generate.py's two nerd-icons loaders share _load_nerd_icons_artifact (sentinel keeps the null-file edge exact); face_coverage.classify rewritten with named locals (with a new characterization test). Two agent findings were wrong and skipped on verification: LOCATE_REG is live (read by previewSpan), and normalizePaletteEntryCore doesn't exist (hallucinated). Skipped on judgment: a RELEASED_BOX constant (mutable-dict aliasing hazard, only ~10 sites) and inlining apply_hover_box_default (its why-docstring earns the named function). Open for Craig: previewFaceAttrs (app-core.js) is test-only with a stale "the gate calls it" docstring — confirm delete vs keep.
*** 2026-06-24 Wed @ 21:53:39 -0400 app.js split — controls.js extracted, remaining splits declined
The highest-value extraction landed (controls.js, see below). Craig's call (2026-06-24): stop there — the remaining clusters (picker, locate, io, tables) are diminishing navigability gain for more churn, so they're declined. The token-at-position pattern is proven and documented if any one is ever wanted.
**** 2026-06-24 Wed @ 19:16:47 -0400 Extracted the control factories to controls.js
Cut the contiguous dropdown / detail-editor / expander cluster (the custom color dropdown state + closeColorDropdown + mkColorDropdown through mkExpander, 205 lines) from app.js into controls.js, spliced back at a CONTROLS_J token via generate.py. app.js dropped 927 to 721 lines. The token sits at the exact extraction point, so the assembled page is byte-identical (just relocated source) — full suite green with no gate changes. mkBoxControl (a lone factory elsewhere in app.js) stayed put; it can join controls.js later.
*** TODO [#D] theme-studio: move the "clear palette" button :feature:studio:
Craig dislikes the current placement (it rides with the update-color and palette-generation controls and is too easy to hit by accident, then re-import the JSON to recover) but has no target placement in mind yet (2026-06-25). Parked until a placement idea lands — the earlier "left-align at the color-column level" was a guess, not a decision. When a target exists: layout/CSS change in the palette area (app.js / styles.css), visual, verify by eye. From the roam inbox 2026-06-16.
*** 2026-06-20 Sat @ 05:53:39 -0400 Tightened the elements-table horizontal layout
Reduced per-cell padding 12px to 8px across all three tables and shortened the redundant "mode-line-highlight (mode-line hover)" label to "(hover)". The weight/slant narrowing landed with the custom-widget task below. Commit 792e09b5.
*** 2026-06-20 Sat @ 05:53:39 -0400 Custom weight/slant dropdowns with previews
Replaced the native weight/slant selects with mkEnumDropdown, themed like the color dropdown. Values are spelled out (semibold not "semi"; unset reads "weight"/"slant"), each popup option previews its own weight or slant, and lock + popup behavior mirrors the color dropdown. Commit 055e0992.
*** 2026-06-20 Sat @ 05:53:39 -0400 Language dropdown sorted with nav arrows
Alphabetized the language list with Elisp pinned as the default, and added the ‹ › arrows that step the selection (clamped) reusing stepViewIndex. #langtest gate. Commit be62ae5b.
*** 2026-06-20 Sat @ 05:53:39 -0400 Moved the lock column to the leftmost position
Lock cell now sits first in all three tables, ahead of the element/face name; the name sort moved to column 1. From the roam inbox 2026-06-20. Commit 4f869aa1.
*** 2026-06-20 Sat @ 06:44:07 -0400 Explanatory hovers on the expander detail labels
Each label in the expander detail row carries a DETAIL_HOVERS tooltip, matching the table-header labels. From the roam inbox 2026-06-20. Commit 2caa4606.
*** 2026-06-20 Sat @ 06:44:07 -0400 View-dropdown lock indicator
The view dropdown prefixes a lock glyph on any view whose elements are all locked. Delivers the lock-indicator half of the custom-view-dropdown task; the custom-menu half is still open. From the roam inbox 2026-06-20. Commit 2caa4606.
*** 2026-06-20 Sat @ 06:44:07 -0400 Expand/collapse-all toggle with disclosure triangles
Per-row expander toggles show ▶/▼ disclosure triangles; a header-level expand-all/collapse-all button per table opens or closes every row at once. From the roam inbox 2026-06-20. Commit 2933a362.
*** 2026-06-20 Sat @ 06:44:07 -0400 Expander stays open across a table rebuild
A package edit rebuilds the table, which had collapsed an open expander mid-edit. An EXPANDED set keyed by element/face reopens the open rows on rebuild. From the roam inbox 2026-06-20. Commit 7382bf53.
*** 2026-06-20 Sat @ 06:44:07 -0400 Added 18 language previews
Tokenized samples.py previews for Racket, Scheme, Haskell, OCaml, Scala, Kotlin, Swift, Lua, Ruby, Perl, R, Erlang, SQL, PHP, Ada, Fortran, MATLAB, Assembly, wired into the language dropdown (28 languages total) with a guard test. From the roam inbox 2026-06-20. Commit 309b1e9a.
*** 2026-06-20 Sat @ 06:44:07 -0400 Moved the box column between style and contrast
Box now sits at column 5 in all three tables, after style and before contrast (reverses the earlier box-to-last). From the roam inbox 2026-06-20. Commit 2a34c3c7.
*** 2026-06-23 Tue @ 13:51:37 -0400 theme-studio preview locate v1 — implemented
Built the preview-element locate feature per the spec (all six phases). Hover any data-face preview element to see its section / face / effective value + source note via title, with the preview-label info line updating to "section > face — value" on mouseover; click an on-pane element to scroll + flash its assignment row; off-pane elements stay hover-only (default cursor). Pure helpers in app-core.js (Node-tested, test-locate.mjs), the stateful previewSpan adapter + cached registry + unified click dispatch in previews.js / app.js, all browser-gated. Verified end to end: run-tests.sh fully green — 262 Node tests, 48 browser gates, ERT + Python + spliced-script parse. Nothing committed yet. Implementation boundary recorded: previewSpan powers the package previews + cross-surface spans; the UI mock keeps its bespoke rendering (its own flashUi locate predates this), now routed through the same locateClick dispatcher (Phase 5). The org-agenda / completion previews become the organic showcase later. [[id:fbcf0e20-1328-42b4-aa36-3401509e7816][theme-studio-preview-locate-spec.org]]
**** 2026-06-23 Tue @ 13:20:39 -0400 Phase 0 — pure-helper extraction landed
Added the five pure locate helpers to app-core.js — buildLocateRegistry(apps,pkgmap,uimap,map), locateFaceMeta(owner,face,registry), formatLocateTitle(meta), previewFaceAttrs(owner,face,registry), isLocateOnPane(owner,currentApp) — all state passed in, returning data not HTML. Owner-qualified registry key (owner+face), effective fg/bg matching the rendered pixels (package inherit via the face's :inherit, UI inherit via UI_INHERIT), per-attribute source notes (direct / inherited-from-X / default / cleared). New test-locate.mjs: 15 pure-Node tests covering the owner-qualified collision, the source-note states, previewFaceAttrs validation, rebuild-after-edit, and the linear/ms perf budget. Verified: run-tests.sh fully green — generate.py inline + 260 Node tests + spliced-script parse + all browser gates + Python/ERT.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 1 — face registry wired
LOCATE_REG: one cached module-level registry built by buildLocateRegistry(APPS,PKGMAP,UIMAP,MAP), rebuilt (rebuildLocateRegistry) at the top of the two preview renderers (buildPkgPreview, buildMockFrame) — the chokepoints every assignment / import / reset / view-switch funnels through before spans render, so it never goes stale and never rebuilds per hover/span. Built lazily, not at declaration, to dodge the inlined UI_INHERIT const's TDZ. locate-onpane recomputed at render via isLocateOnPane. Gate #locatetest: registry presence, owner-qualified keys, rebuild-after-edit. run-tests.sh green.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 2a — previewSpan adapter + os delegation
previews.js: previewSpan(owner,face,text) reads the live globals, dispatches by surface, emits data-owner-app + data-face + the locate-onpane class (on-pane only), and os delegates to it. Text stays trusted preview HTML (callers pre-escape entities) — previewSpan does NOT re-escape it, preserving the old os() contract and avoiding double-escaping &lt;. Gate #locatetest extended; all existing package-preview gates (mdtest/mupreviewtest/gnustest/previewlinktest/mocktest/autodimtest) still pass unchanged.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 2b — owner-aware assertPreviewFaces
Rewrote the gate validator to resolve each element's owner from data-owner-app (defaulting to the preview's app for bare spans), validating package faces against APPS[owner].faces and @ui against UIMAP keys. Accepts intentional off-pane + @ui spans, rejects a bad owner. Existing same-app preview gates still pass.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 2c — @ui rendering in previewSpan
Added ulocateCss(face) (effFg(resolveUiAttr) over UIMAP, matching the registry's effective value) as the @ui branch of previewSpan. Gate: a @ui face (minibuffer-prompt) renders its real color off a package preview and is off-pane.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 2d — gate-only showcase fixture
#showcasetest: a synthetic host package-preview context with one package-owned off-pane span + one @ui (minibuffer-prompt) off-pane span — each renders in its owner's real color, is hover-only (no locate-onpane), and passes the owner-aware validator. No user-facing preview change.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 3 — hover title + info line
previewSpan now carries the full locate title (formatLocateTitle, attribute-escaped) on every element; buildPkgPreview wires mouseover → the pkgprevlabel info line shows locateInfoLine "section > face — value" (title is the deterministic fallback), restored on mouseleave. New pure locateInfoLine in app-core.js (+2 Node tests). Gate #locatehovertest: exact title string, direct/cleared notes, the info line update + restore.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 4 — click flash + cursor split
Added .locate-onpane{cursor:pointer} to styles.css (off-pane keeps the default cursor). Click routes through the unified locateClick dispatcher: on-pane flashes its assignment row (flashRow, no persistent selection), off-pane / unassigned inert. Gate #locateclicktest: on-pane flash, off-pane unflashed, the cursor/class split.
**** 2026-06-23 Tue @ 13:51:37 -0400 Phase 5 — locate-dispatch cleanup
One locateClick(e, defaultOwner) replaces both the buildPkgPreview and buildMockFrame face-click branches — owner from data-owner-app or the surface default, on-pane-only for owner-tagged spans, bare spans (generic / auto-dim / UI mock) stay clickable. The data-k syntax path stays separate. #mocktest still green (mock click unchanged); #locateclicktest covers the unified path on both surfaces.

*** TODO [#D] theme-studio preview locate: reveal off-pane element in owning pane :feature:theme-studio:
vNext from the preview-locate spec: add a "reveal in pane" affordance for off-pane preview elements (switch to the owning pane and scroll to the row) if the hover-only model proves too manual. V1 deliberately keeps off-pane elements non-clickable. [[id:fbcf0e20-1328-42b4-aa36-3401509e7816][theme-studio-preview-locate-spec.org]]
*** TODO [#D] theme-studio preview locate: syntax/code tier into unified registry :feature:theme-studio:
vNext from the preview-locate spec: fold the data-k syntax/code tier into the locate registry. V1 leaves it on its existing cp.onclick -> flashAssign path. [[id:fbcf0e20-1328-42b4-aa36-3401509e7816][theme-studio-preview-locate-spec.org]]
*** TODO [#D] theme-studio preview locate: keyboard-focus info strip :feature:theme-studio:
vNext from the preview-locate spec: make preview spans focusable and drive a hover/focus info strip for keyboard-only wayfinding. V1 wayfinding is pointer-driven (recorded accessibility caveat). [[id:fbcf0e20-1328-42b4-aa36-3401509e7816][theme-studio-preview-locate-spec.org]]
*** 2026-06-24 Wed @ 22:30:00 -0400 converter :inherit on UI faces — verified already correct, not reproducible
The reported bug (build-theme.el's UI tier dropping :inherit for inherit-only UI faces) does not reproduce in the current code. uiFaceBlank carries an inherit field, exportObj dumps the full UIMAP (inherit included), and build-theme/--attrs reads it. Direct test: a theme.json with ui face {inherit: mode-line, fg: null, bg: null} fed to build-theme/--ui-face-specs emits ((mode-line-inactive ((t (:inherit mode-line))))) — the :inherit survives. Closed as already-fixed / stale.
*** TODO [#D] theme-studio CIEDE2000 DeltaE option           :feature:studio:
Deferred from the perceptual color metrics spec (vNext). v1 uses DeltaE-OK on its native scale with a 0.02 threshold (decided); revisit CIEDE2000 only if the native OKLab scale proves too unfamiliar or poorly calibrated for palette distinguishability. Spec: [[id:15db8ae3-fc14-49f3-9ed5-d5ff59790904][spec]] (vNext candidates; review folded in 2026-06-08).
*** TODO [#D] theme-studio low-contrast preset/mask mode     :feature:studio:
Deferred from the perceptual color metrics spec (vNext). After raw OKLCH/APCA/DeltaE readouts exist, decide whether to add a named low-contrast workflow: APCA Lc bands, a contrast ceiling/floor mask, or a "soft" sibling to the existing any/AA+/AAA picker mask. Spec: [[id:15db8ae3-fc14-49f3-9ed5-d5ff59790904][spec]] (vNext candidates; review folded in 2026-06-08).
*** TODO [#D] theme-studio per-tier reseed controls          :feature:studio:
Deferred from the seeding-engine spec (vNext). V1 reseeds all three guide-owned tiers at once; later consider separate "reseed syntax", "reseed UI", and "reseed package/org" controls if all-at-once proves too blunt. Spec: [[id:b70b37f2-37df-4c8e-ac2f-1f20d12e33dd][spec]] (vNext; review folded in 2026-06-08).
*** TODO [#D] org-faces: dim variants and retire dupre-org-* :feature:theme-studio:
vNext from the org-faces spec: org-faces-*-dim variants wired into auto-dim so keywords stay legible in unfocused windows, and migrate or retire the legacy dupre-org-* set. [[id:35578114-8c29-43af-97a2-fdfea01a802e][org-faces-spec-implemented.org]]
*** TODO [#D] Face diagnostic popup — theme-studio bridge (vNext)   :feature:
vNext for the face/font diagnostic tool: interactivity — "send this face to theme-studio", jump-to-theme-spec, any write path. Deferred per [[id:98f065cf-8bd5-46a0-ac24-da94d66855ad][the spec]]'s scope tiers.
*** 2026-06-16 Tue @ 05:10:55 -0500 Alphabetized the assignment-view package dropdown
The package-faces optgroup (below the @code/@ui editor entries) now lists apps alphabetically by display label. Root cause: =buildViewSel= iterated =for(const app in APPS)=, and =generate.py= builds APPS as bespoke apps first then inventory apps, so the combined list wasn't alphabetical. Fix is localized to the view-list build per the plan: added a pure =appViewKeysSorted(apps)= helper in =app-core.js= (sorts keys by label, case-insensitive, key fallback when a label is missing) and =buildViewSel= iterates it. TDD: 4 node tests in =test-app-core.mjs= (red->green); updated the #viewtest browser gate from asserting insertion order to asserting =appViewKeysSorted(APPS)=; full theme-studio suite green (Python + Node + all browser gates). Commit =afd2ddad=, pushed. Visual sign-off optional (gate already confirms the DOM order).
*** 2026-06-16 Tue @ 06:11:30 -0500 Contrast cell: dropped PASS/FAIL, verdict moved to the hover
Craig's call (option a + hover): the contrast cell now shows just the rating-colored number (green = passes AAA, grey = passes AA, red = fails AA), and the WCAG meaning lives in a hover. Added a pure =contrastTitle(r)= to =app-util.js= (4 node tests), changed =crHtml= (app.js) to drop the verdict word and set =title=, kept =verdictFor= for the covered-overlay worst-case readout (untouched, #contrasttest still green). New #crtest browser gate; full theme-studio suite green. Commit =9e99749d=, pushed.
*** TODO [#B] theme-studio: package coverage for pearl, wttrin, chime :feature:studio:
Three projects shipped themeable faces and asked theme-studio to render accurate previews. Data lives in the PROCESSED handoff files.
**** TODO pearl — 6 faces + overlay-driven appearance
Six faces in the =pearl= customize group plus overlay-driven appearance a raw buffer read won't show. =inbox/PROCESSED-2026-06-23-2239-from-pearl-theme-studio-pearl-spec.org= + cover + =sample-pearl-buffer.org=.
**** TODO emacs-wttrin — 4 new faces
Was hardcoded "gray60"; now four customizable faces (branch =feature/themeable-faces=). =inbox/PROCESSED-2026-06-23-2253-from-emacs-wttrin-wttrin-faces-handoff.org= + rendered sample.
**** TODO chime — 4 themeable modeline faces
Four modeline faces shipped (081d76e). =inbox/PROCESSED-2026-06-23-2326-from-chime-chime-added-four-themeable-modeline.org=.
*** PROJECT [#B] theme-studio guide-support features :feature:studio:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
From the color-assignment guide work (2026-06-08): make the tool support the guide without mandating it — everything a seed, an advisory, or a view, never a gate. Two specs to write, both deriving from the rewritten guide and its seed table ([[file:scripts/theme-studio/theme-coloring-guide.org][theme-coloring-guide.org]]).
**** 2026-06-08 Mon @ 19:08:00 -0500 Seeding-engine spec written and Ready
[[id:b70b37f2-37df-4c8e-ac2f-1f20d12e33dd][theme-studio-seeding-engine-spec-doing.org]] — role table + face→role maps for syntax/UI/org, OKLCH shade generation, reseed dupre-revised to the compact mapping. Codex-reviewed, Ready. Implementation tracked under the seeding-engine parent below.
**** TODO Guide-support views and advisories spec
Five optional surfaces, all dismissible and non-blocking, in one collapsible panel where they advise: (1) CVD-simulation toggle on previews (deuteranopia/protanopia/tritanopia); (2) squint/blur preview toggle; (3) lightness-ramp view + palette advisories (accent count over 6-8, roles separated only by red/green) — depends on the OKLCH/ΔE core; (4) definition-vs-call / weight advisories; (5) state-over-syntax preview (region/search/diff tint over real syntax-colored text). Sequence: rewritten guide reviewed → seeding-engine spec → this. Advisories (3, 4) layer on the perceptual-metrics feature.
*** TODO [#C] Dupre diff-changed / diff-refine-changed legibility :bug:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Surfaced 2026-06-07 from a pearl session designing its modified-ticket indicator (pearl marks a changed field by inheriting =diff-changed=). dupre's =diff-refine-changed= is bright gold (#ffd700) under near-white text (#f0fef0) -- WCAG contrast ~1.35, unreadable as a plain background. It only looks fine inside diff-mode because diff-mode overlays its own dark foreground. =diff-changed= (#875f00 amber) is ~5.49, readable but off the modus model. Every modus variant keeps both faces legible (contrast 9-16) by pairing a dark low-saturation background with a hue-matched foreground.

Ask:
1. Rework dupre's =diff-changed= and =diff-refine-changed= on modus lines: dark low-saturation background, legible foreground (plain default fg for simplicity, or hue-tinted per modus -- decide), and keep refine slightly stronger than changed (refine is the word-level emphasis inside a changed region; modus keeps them distinct).
2. While there, audit dupre's broader diff/palette faces against modus conventions (background/foreground tinting, contrast targets) and flag where it diverges.

Reference values -- modus-vivendi: refine-changed bg #4a4a00 fg #efef80, changed bg #363300 fg #efef80. modus-operandi: refine-changed bg #fac090 fg #553d00, changed bg #ffdfa9 fg #553d00.

Side-by-side legibility render: [[file:assets/2026-06-07-dupre-diff-face-legibility-compare.png][assets/2026-06-07-dupre-diff-face-legibility-compare.png]].
** TODO [#B] org-capture popup leaks f12 / f10 / f11 / ai-term keys :bug:
While the org-capture popup is open, the global F-keys (the =f12= term, =f10= / =f11=, the ai-term family) still fire and pop a terminal over the capture. Disable those keys for the duration of the capture popup if there's a clean way. Research first and report; if it's too invasive, defer or cancel rather than force it. From the roam inbox 2026-06-24.
** TODO [#B] VAMP — extract music-config into a standalone player :feature:refactor:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Build VAMP ("VAMP Audio Music Player"), a standalone, publishable Emacs music player at =~/code/vamp= — derived from a maintained subset of EMMS, depending on the EMMS package not at all, with MPV and mpd behind a generalized adapter API. =.emacs.d= keeps thin glue (=vamp-config.el=: keybindings, paths, dashboard); archsetup owns OS wiring (Super+/ launcher, m3u MIME). Models the =linear-config= → =pearl= migration.

Brainstorm complete 2026-06-22 — validated design at [[file:docs/design/vamp-music-player.org][docs/design/vamp-music-player.org]]. It builds on the prior EMMS-removal work ([[file:docs/specs/music-config-without-emms-spec.org][spec]] + [[file:docs/design/music-config-without-emms-review.org][2026-05-15 review]]), confirming its B1/B2/B4/S3 decisions and pivoting four things (publishable-now, two adapters + generalized API, VAMP name, desktop integration).

Next: (1) revise the spec to the new direction; (2) spike the risky assumptions (mpd dumb-single-file-player contract; m3u =.desktop= on Hyprland); (3) =/start-work= against the revised spec — pure-helper extraction (review Migration Plan step 1) is the safe first phase. Priority [#C] is a placeholder pending Craig's call.

** TODO [#C] nov: sepia reading view (dark bg, tan/sepia text) :feature:
A sepia setting for =nov-mode=: keep a dark background, render the letters in a tan/sepia color. nov defines no faces of its own and leans on shr, so the path is buffer-local face-remapping (=face-remap-add-relative= on =default= / =shr-text= / =variable-pitch=) in a nov-mode hook, toggled per a sepia preference. Overlaps the "epub/nov reading color" note under "Route hardcoded theme colors through the theme" (the removed =#E8DCC0= sepia plus "needs a themeable reading face") — reconcile with that themeable-face direction. From the roam inbox.
** TODO [#C] pdf-view: epdfinfo crashes loading some PDFs (large IA scans) :bug:
=epdfinfo server quit. restart y/n?= when opening certain PDFs, so pdf-view-mode never engages and the file lands in the wrong mode. Reproduced with =~/sync/books/Karl Jaspers/Karl Jaspers_ Basic Philosophical Writings _ Selections (49298)/Karl Jaspers_ Basic Philosophical Writings - Karl Jaspers.pdf= (576-page, 31MB Internet Archive scan).
Diagnosis: the PDF is structurally valid (=qpdf --check= clean; =pdfinfo= reads it) and poppler renders its pages (=pdftoppm= pages 1 and 300 succeed), so it isn't corruption or a poppler-render crash. epdfinfo crashes loading the document, likely on the tagged-PDF structure / metadata stream the IA scan carries (=Tagged: yes=, =Metadata Stream: yes=), a known epdfinfo trouble class. =auto-mode-alist= maps =.pdf= -> =pdf-view-mode= correctly, so-long is off, and there's no large-file prompt (=large-file-warning-threshold= nil).
Fix options (Craig to choose): (1) re-save the file to strip what crashes epdfinfo (=mutool clean= / ghostscript / =qpdf --replace-input=), keeping a backup -- fixes this file, recurs on the next bad scan; (2) graceful fallback in =pdf-config.el= -- when epdfinfo dies on a PDF, open it in zathura (already bound to =z=) instead of the dead pdf-view buffer, robust for the whole class; (3) both. From the roam inbox.
** PROJECT [#B] Architecture review follow-up from 2026-05-03 :refactor:

High-level pass over =init.el=, =early-init.el=, and all 104 files in
=modules/=. The main theme: the config works, but load order, startup side
effects, credentials, and test measurement are more implicit than they should
be. Use this project as the parent tracker; each child below should land as a
small, reviewable change.

Review snapshot:
- =modules/= has 104 files and about 24k lines including =init.el= and
  =early-init.el=.
- =init.el= eagerly =require=s nearly every module.
- =make coverage= passed when allowed to write the test scratch directory.
- Coverage report: =3240/4952= executable lines, =65.43%=, across 49 module
  files. Caveat: 55 module files do not appear in the report at all, so the
  real project confidence is lower than the raw percentage suggests.

*** 2026-05-15 Fri Consolidate shared utility helpers :refactor:
CLOSED: [2026-05-15 Fri]

Helpers are scattered across feature modules where they were first needed.
Some are duplicated, and some private helpers are generic enough to belong in a
shared foundation library. This is adjacent to the load-graph refactor because
central helper ownership reduces hidden inter-module dependencies, but it
should remain a sibling project so load-order batches stay small and
reviewable.

Guidance:
- Do not extract a helper until at least two callers are clearly the same
  shape.
- Prefer growing =system-lib.el= first; split into topic libraries only if it
  becomes too broad or starts pulling coarse dependencies into foundation
  startup.
- Keep one helper extraction per commit.
- Move unit tests with the helper. Consumers should keep behavior/integration
  coverage.
- Do not add heavy package dependencies to foundation helpers.

**** DONE [#B] Write full utility consolidation design spec :refactor:
CLOSED: [2026-05-04 Mon]

Create a design document that inventories candidate helper extractions,
recommends grouping and naming, explains how the helpers fit into existing
library modules, defines migration phases, and identifies testing/rollback
rules.

Spec: [[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][docs/specs/utility-consolidation-spec-doing.org]]

Verify 2026-05-04:
- Added [[id:fc2e3926-b4a1-4b45-92eb-20841e13f655][docs/specs/utility-consolidation-spec-doing.org]].
- Spec includes framing questions, existing library fit, proposed grouping,
  concrete pull/rename table, migration phases, test strategy, acceptance
  criteria, risks, open questions, and recommended first commits.
- Parsed the spec and =todo.org= with =org-element=.
- Committed the tracked spec as =3ea4707=.
- Incorporated complete review feedback in =dd77ebd=, including API behavior
  contracts, speculative-extraction rules, =system-lib= dependency budget,
  inventory/audit artifacts, test relocation policy, commit type guidance,
  =use-package :if= load-order policy, and Phase 5 cache-design addendum
  requirement.

**** DONE [#B] Inventory private helpers across modules :refactor:
CLOSED: [2026-05-10 Sun]

Walk every module and tag private helpers as genuinely module-specific,
generic-but-trapped, or duplicated. Capture likely consumers and any dependency
cost before extracting.

Candidate families:
- shell argument formatting,
- executable lookup with user-visible warnings,
- argv-based process runners,
- path containment/safe-base predicates,
- Org-safe heading/property/body text sanitizers,
- cache-with-TTL plus invalidation hooks,
- warning/message wrappers.

Verify 2026-05-10:
- Added [[file:docs/design/utility-inventory.org][docs/design/utility-inventory.org]] covering the 30 entries in the spec's
  Candidate Extraction Table grouped by family (executable discovery, shell
  quoting, process runner, file/path, external-open, Org-safe text, cache,
  logging, macros/debug, theme I/O, string).
- For each helper recorded: visibility, dependencies, side effects, callers
  (production + test), test files, priority, decision (Migrate / Leave / Defer)
  with rationale.
- Decisions Summary: 11 Migrate, 3 Leave, 13 Defer.
- Concrete next-action list groups Migrate items by Phase (2 = foundation
  helpers, 3 = Org-safe text, 4 = external-open consolidation) for the order
  the spec recommends.
- Discoveries: =cj/log-silently= has 10 production callers (more than the
  spec's table suggested -- defer is the right call); =cj/--file-manager-program-for=
  shipped today in =dirvish-config.el= is the new form of OS-dispatch
  consolidation and should fold into =cj/external-open-command= during Phase 4.

**** DONE [#B] Extract executable lookup with warning helper :refactor:
CLOSED: [2026-05-10 Sun]

Create a generic helper such as =cj/find-executable-or-warn= from the useful
=mail-config= pattern. It should return the executable path or nil and produce
a clear warning when the executable is missing.

Done 2026-05-10:
- Shipped as =cj/executable-find-or-warn= in =modules/system-lib.el=
  (commit =c75e36f4=, extracted from =mail-config=).
- First consumer rewired in =12c2cb14= (=cj/set-wallpaper= in
  =dirvish-config.el=).

**** DONE [#B] Extract argv-based process runner helper :refactor:
CLOSED: [2026-05-10 Sun]

Generalize the =coverage-core= process pattern into a dependency-light helper
that captures output and signals a clear =user-error= with command/status/output
on failure. Consider a small git wrapper only after the generic runner exists.

Done 2026-05-10:
- Shipped =cj/process-output-or-error= plus the =cj/git-output-or-error=
  wrapper in =modules/system-lib.el= (commit =57e558ce=, extracted from
  =coverage-core=).

**** DONE [#B] Extract Org-safe text sanitizers :refactor:
CLOSED: [2026-05-10 Sun]

Move heading/property/body sanitization into a shared helper once at least one
non-calendar consumer is ready. Keep behavior explicit so external text cannot
accidentally create headings or malformed properties.

Done 2026-05-10:
- Shipped =modules/cj-org-text-lib.el= (renamed to its final =-lib= form in
  commit =0f9e3087=) with three sanitizers: =cj/org-sanitize-body-text=,
  =cj/org-sanitize-property-value=, =cj/org-sanitize-heading=.

*** 2026-05-15 Fri Make coverage reporting account for untracked modules :test:
CLOSED: [2026-05-15 Fri]

The current coverage result is useful but easy to overread. =make coverage=
reported =65.43%= for files that undercover saw, but only 49 of 104 module
files appeared in =.coverage/simplecov.json=.

Definition: in this task, "untracked modules" means repository-owned
=modules/*.el= files that should be part of the Emacs configuration coverage
universe but have no entry in =.coverage/simplecov.json= after =make coverage=
runs. These files may be missing because no test required them, because loading
was skipped due to package/environment guards, or because instrumentation did
not see them. They are distinct from tracked modules with 0% covered lines,
which already appear in SimpleCov and can be scored directly.

Completed 2026-05-15:
- Both child tasks are done.
- =make coverage-summary= reports missing modules explicitly and also reports a
  separate project-module score where missing modules count as 0%.
- Focused summary tests and byte-compilation of the summary helper passed.

**** 2026-05-15 Fri Teach the coverage report to list modules missing from SimpleCov
CLOSED: [2026-05-15 Fri]

Expected outcome:
- Compare =modules/*.el= against paths present in =.coverage/simplecov.json=.
- Show a separate "not in report" section.
- Do not silently fold those files into the percentage until we decide the
  semantics. A visible missing-file count is enough for v1.

Done 2026-05-15:
- =make coverage-summary= now compares direct =modules/*.el= files on disk
  against the module paths present in =.coverage/simplecov.json=.
- The terminal report appends a =Not in SimpleCov report= section with a count
  and the missing module paths.
- Missing modules are explicitly excluded from the displayed percentage for
  now; the policy question below remains open.
- Added focused tests in =tests/test-coverage-summary.el= for missing-module
  reporting and for ignoring =.elc= files and nested paths outside direct
  =modules/*.el= ownership.

**** 2026-05-15 Fri Decide whether unreported modules count as 0% coverage
CLOSED: [2026-05-15 Fri]

This is a policy decision:
- Counting missing modules as 0% gives a more honest project-level number.
- Keeping the current number is useful for "instrumented executable lines only".

Recommendation: display both:
- Instrumented coverage: current SimpleCov percentage.
- Project module coverage: includes unreported module files as 0% or reports
  them separately with an explicit caveat.

Decision 2026-05-15:
- Keep the existing SimpleCov percentage as the line-weighted
  =instrumented coverage= number. It only covers modules that SimpleCov saw and
  has real executable-line denominators for.
- Also display a separate module-weighted =project module coverage= score over
  all direct =modules/*.el= files. Modules present in SimpleCov contribute their
  per-file coverage percentage; modules absent from SimpleCov count as 0%.
- Do not pretend missing modules have known executable-line counts. Counting
  them as 0% at the module level is honest about risk without inventing a line
  denominator.

Done 2026-05-15:
- =make coverage-summary= now prints both the existing line-weighted summary
  and a separate =Project module coverage= line that includes missing modules
  as 0%.
- The missing-module section now states that missing modules count as 0% in the
  project-module score.
- Updated =tests/test-coverage-summary.el= to assert the policy and the
  displayed project-module percentage.

*** 2026-05-15 Fri Add a lightweight architecture smoke test for startup contracts :test:
CLOSED: [2026-05-15 Fri]

After the above refactors start, add one or two smoke tests that protect the
architecture instead of individual functions.

Candidate checks:
- All modules can be loaded directly with only =modules/= on =load-path=, or
  skipped with a clear external package reason.
- No module other than =keybindings.el= binds =C-;= itself.
- Startup-only modules do not run timers in batch test mode.

Keep this small. The goal is to catch accidental return to hidden load-order
coupling, not to build a full static analyzer.

Done 2026-05-15:
- Added =tests/test-architecture-startup-contracts.el= with two source-level
  smoke checks:
  - only =keybindings.el= may globally own the exact =C-;= prefix;
  - top-level timer scheduling forms must be guarded by =noninteractive= so
    batch/test loads do not schedule startup timers.
- Gated existing startup timers in =org-agenda-config.el=,
  =org-refile-config.el=, =quick-video-capture.el=, and =wrap-up.el=.
- Focused tests passed for the new architecture smoke file and the affected
  agenda/refile helpers.

*** TODO [#A] Un tangle the eager =init.el= load graph :refactor:

=init.el= currently functions as the dependency graph by eagerly requiring
almost every module in a fixed order. That makes modules harder to test in
isolation and hides real dependencies behind "loaded earlier in init.el"
assumptions.

Spec: [[id:e1fd137e-e164-42f4-a658-f4d32fbe3228][docs/specs/init-load-graph-spec-doing.org]]

**** 2026-05-25 Mon @ 07:59:20 -0500 Wrote full design spec for the =init.el= load-graph refactor :refactor:

Create a design document that defines the target architecture, module
categories, migration phases, test strategy, acceptance criteria, and risk
controls for untangling the eager =init.el= load graph.

Review incorporation:
- Treat helper consolidation as adjacent architecture work, not a direct
  acceptance criterion for the load-graph refactor.
- Mention utility extraction guardrails in the spec so Phase 2 dependency work
  has a clear rule for duplicated helpers found along the way.

Verify 2026-05-04:
- Added [[id:e1fd137e-e164-42f4-a658-f4d32fbe3228][docs/specs/init-load-graph-spec-doing.org]].
- Incorporated review feedback by making utility consolidation an explicit
  sibling project with guardrails and candidate helper families.
- Parsed the spec and =todo.org= with =org-element=.
- Committed the tracked spec as =0528475=.

**** 2026-05-24 Sun @ 17:07:03 -0500 Classified modules by role and startup requirement
Built [[file:docs/design/module-inventory.org][docs/design/module-inventory.org]] across 9 batches: 101 of 102 init.el-required modules annotated with the load-graph header contract (Layer, Category, Load shape, Eager reason, Top-level side effects, Runtime requires, Direct test load) and tabulated in the inventory. Added =tests/test-init-module-headers.el= to enforce the contract on each classified module. Retired the three vague =init.el= comments (latex-config WIP, prog-shell "combine elsewhere", "Modules In Test" banner) into real tasks. Recorded seven hidden =cj/custom-keymap= / cross-module dependencies for the Phase 2 dependency pass. Tagged the span =load-graph-classify-start..load-graph-classify-end=. elfeed-config is the one module left, pulled to its own task below.

**** 2026-05-25 Mon @ 08:35:33 -0500 Annotated elfeed-config load-graph header
Added the load-graph header to elfeed-config (Layer 4, O/D/P, current load shape eager with an eager reason, target command-loaded; runtime requires user-constants, system-lib, media-utils), added it to the header-contract allowlist in =tests/test-init-module-headers.el= (Batch 8), and moved it in =docs/design/module-inventory.org= from the Deferred/Pending sections into the Batch 8 table. Inventory now 102 of 102 classified. The header's "Load shape" records the current shape (eager, required in init.el) per the weather-config/games-config convention; "command-loaded" is the target, in the inventory's Target column. Shipped as a522e553.

**** 2026-05-24 Sun @ 18:35:06 -0500 Made hidden module dependencies explicit
Fixed the seven hidden dependencies the classification surfaced: system-defaults now requires host-environment and user-constants at runtime (was eval-when-compile); custom-buffer-file, dev-fkeys, calendar-sync, and video-audio-recording require keybindings and drop their =(when (boundp 'cj/custom-keymap) ...)= shims; flycheck-config and mail-config require keybindings for their cj/custom-keymap bindings. Removed a dead =eval-when-compile (defvar cj/custom-keymap)= in transcription-config (the var was never used).

No init.el load-order change — keybindings and the foundation modules already load before these, so the explicit requires are no-ops at startup and only fix standalone/test loading.

Verified each fix with a fresh =emacs --batch (require 'X)=, then swept all ~100 modules standalone: every one loads or fails only with a clear missing-package message (the spec's Phase 2 exit bar). Full =make test=, =make validate-modules=, and an init smoke all pass. Module headers and the inventory's hidden-dependency section updated to mark the seven resolved.

**** DOING [#A] Defer feature modules behind autoloads, hooks, and commands :refactor:

Once dependencies are explicit, reduce the number of modules required at
startup. Start with lower-risk feature modules:
- Entertainment and optional integrations: =games-config=, =music-config=,
  =weather-config=, =slack-config=, =erc-config=.
- Heavy document/media modules: =pdf-config=, =calibredb-epub-config=,
  =video-audio-recording=, =transcription-config=.
- AI/rest tooling: =ai-config=, =restclient-config=, =ai-conversations=.

Do this incrementally. After each batch:
- Restart Emacs interactively.
- Run =make test= or at least targeted tests.
- Check that keybindings still resolve and which-key labels still appear.

***** 2026-06-21 Sun @ 01:53:55 -0400 Deferred games-config (batch 1, module 1)
Replaced =(require 'games-config)= in init.el with explicit autoloads for =malyon= and =2048-game= → games-config; the module now loads on first game-command use instead of at startup. games-config.el: =:defer 1= → =:defer t :commands=, header Load shape eager→command. package.el already autoloads both commands, so routing through games-config only preserves the one setting it owns (=malyon-stories-directory=), applied via use-package =:config= when malyon loads. Verified the autoload→module→package→config chain in batch. Test: =tests/test-init-defer-games.el= (commands resolve with the module unloaded; config applies on load). Inventory row eager→command; header-contract 4/4 (still allowlisted), full =make test= green. Shipped as 03d8b587. Daemon keeps it loaded until restart — interactive restart smoke pending (see Manual testing).

**** 2026-05-24 Sun @ 19:59:01 -0500 Centralized custom keymap registration
Added cj/register-prefix-map and cj/register-command to keybindings.el (commit 47f222f6) with test-init-keymap-registration.el, then migrated all 31 cj/custom-keymap registration sites across 24 modules onto the API. Consumers no longer reference cj/custom-keymap directly — keybindings.el is the sole owner of the prefix, and modules require keybindings to reach the API.

Verified behavior-preserving by dumping every C-; binding before and after: identical, 279 bindings, each resolving to the same command. Byte-compiled all 24 migrated files (no new free-variable warnings — the cj/custom-keymap coupling is gone), and full make test, validate-modules, and an init load all pass. which-key label blocks were left intact; they use string key descriptions and never assumed cj/custom-keymap existed.

Related existing task: [#B] "Review and rebind M-S- keybindings".

*** TODO [#A] Move package bootstrap out of =early-init.el= where possible :refactor:

=early-init.el= currently handles package archives, package refresh, installing
=use-package=, and =use-package-always-ensure=. That is more than early startup
needs and can make startup network-sensitive.

**** TODO [#A] Split early startup from package bootstrap :refactor:

Keep =early-init.el= focused on things that must happen before package and UI
startup:
- GC/file-name-handler startup tuning.
- =load-prefer-newer=.
- frame/UI suppression.
- minimal debug behavior.

Move package archive setup and =use-package= installation to a normal module or
bootstrap command, unless there is a specific reason it must run in
=early-init.el=.

Acceptance criteria:
- Fresh install/bootstrap still works from a documented command or script.
- Normal startup does not refresh archives or install packages unexpectedly.
- Offline startup remains quiet and predictable.

**** TODO [#A] Revisit package signature policy

=package-check-signature= is disabled. Decide whether that is still necessary
for the localrepo/mirror workflow.

Expected outcome:
- Prefer signatures on by default.
- If signatures must be disabled for local mirrors, scope that exception and
  document why.
- Add a note to the local repository docs so future package failures do not
  lead to permanent insecure defaults.

** PROJECT [#B] F-key Completion :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-02
:END:

The L546 ticket "Rework dev F-keys" landed roughly 75% as of the 2026-05-27 audit. F4 (compile+run dispatcher, project-type detection, clean-rebuild, projectile cache revert), F7 (coverage), and the format-key migration off F6 are all shipped with ERT coverage. F6 ships Phase 2a only — "All tests" and "Current file's tests" via plain F6 and C-F6.

Phase 2b remains: per-language test discovery, the "Run a test..." menu entry, M-F6 fast path, buffer-local last-test memory, and the spec-mandated "No tests found for <buffer>" error. The =dev-fkeys.el= header (L35–46) already sketches the tree-sitter capture-then-filter pattern needed to work around Emacs bug #79687 on the emacs-30 branch.

Two smaller cleanups also fall out: the header comment claims TS/JS is "punted for v1" while the cmd-builder at =dev-fkeys.el:384= actually emits a vitest/jest command, and the cmd-builder is a likely home for =cj/--tests-in-buffer= once it lands.

Open: helper home — keep =cj/--tests-in-buffer= in =dev-fkeys.el= (per L546 spec) or push it into =test-runner.el= (per the parallel "Fix up test runner" thread). Elisp "Run a test..." — drill into individual =ert-deftest= names, or keep the current regex-aggregate (=make test-name TEST=^test-<stem>-=).

*** TODO [#B] Per-language test discovery helper :feature:test:
Build =cj/--tests-in-buffer= returning a list of test names; tree-sitter capture-then-filter for python/go/ts/js per the bug #79687 workaround in =dev-fkeys.el= L35–46; sexp scan for elisp =ert-deftest= forms.

*** TODO [#B] F6 Run-a-test menu entry :feature:test:
Add "Run a test..." to =cj/f6-test-runner= candidates; pre-select =cj/--last-test-run=; signal =user-error= "No tests found for <buffer>" when discovery returns nil.

*** TODO [#B] M-F6 fast path :feature:test:
Bind =M-<f6>= to a thin wrapper that calls the same "Run a test..." path directly; release the reservation comment at =dev-fkeys.el:541=.

*** TODO [#B] Buffer-local cj/--last-test-run :feature:test:
Add the buffer-local var, set it on each "Run a test..." selection, use it as the completing-read default so a bare RET re-runs the last test.

*** TODO [#B] TS/JS coverage status sync
Update the =dev-fkeys.el= header comment (L33) — TS/JS is no longer punted; the cmd-builder at L384 emits vitest/jest. Document the prefer-vitest fallback.

** PROJECT [#B] Module-by-module hardening
:PROPERTIES:
:LAST_REVIEWED: 2026-06-05
:END:

Review every file in =modules/= and capture concrete bugs, tests, refactors,
and design improvements as child tasks. This is intentionally separate from the
top-level architecture review: the architecture project tracks cross-cutting
load/startup/test structure, while this project tracks module-specific work.

Audit reconciliation 2026-05-27: four sessions between 2026-05-23 and
2026-05-26 drained the umbrella significantly. Roughly 24 of the original
~89 sub-task findings remain open (TODO/DOING/VERIFY) across all six tracks.
Notable shipped work since the 2026-05-22 review: user-constants
filesystem-init split, system-defaults smoke tests, env-desktop-p doc fix,
popper-config removal, UI/navigation runtime smoke coverage, mu4e
org-contacts coverage, prog-lisp smoke coverage, Org export tool guards.
The six =***= track tasks are all still DOING (track status unchanged);
the change is mass of completed sub-work, not track status.

Re-review pass 2026-05-15:
- Each of the six existing review tracks (foundation, custom editing, UI /
  navigation, Org workflow, programming workflow, integrations and
  applications) was re-walked as if it had not been reviewed before.
- 32 new sub-task findings filed across the tracks above (foundation 5,
  custom editing 6, UI / navigation 9, Org workflow 3, programming 6,
  integrations 2).  Findings already covered by an existing sub-task were
  dropped during consolidation.
- A separate =Review newly added modules= task lists the 24 modules that
  were either added after the parent task was written (post-2026-04) or
  fell outside the original scope lists.  Each is routed to its target
  track; module-specific findings are filed under the relevant track.

Review protocol for each module:
- Read the module directly, not just the test names.
- Check runtime dependencies, top-level side effects, keybindings, timers,
  external executable assumptions, secrets, host-specific paths, and user-data
  writes.
- Check existing test coverage and whether tests protect the highest-risk
  behavior.
- Promote larger findings into child =PROJECT= tasks with phases. Keep small
  fixes as plain =TODO= tasks.

Priority scheme: use the top-level =Priority Scheme= section in this file.

Suggested review order:
1. Foundation: =system-lib=, =user-constants=, =host-environment=,
   =system-defaults=, =keybindings=, =config-utilities=, =early-init=,
   =init=.
2. Custom editing utilities: =custom-*=, =external-open=, =media-utils=.
3. UI and navigation: =ui-*=, =font-config=, =modeline-config=,
   =selection-framework=, =mousetrap-mode=, =popper-config=.
4. Org workflow: =org-*=, =calendar-sync=, =hugo-config=, =gloss-config=.
5. Programming workflow: =prog-*=, =dev-fkeys=, =test-runner=,
   =coverage-*=, =vc-config=.
6. Integrations and applications: mail, Slack, ERC, Elfeed, EWW, Dirvish,
   PDF, Calibre, music, recording/transcription, AI/rest tooling.

*** DOING [#B] Harden foundation modules

Scope:
- =system-lib.el=
- =user-constants.el=
- =host-environment.el=
- =system-defaults.el=
- =keybindings.el=
- =config-utilities.el=
- =early-init.el=
- =init.el=

Expected output:
- Add one child task for each actionable finding.
- Note "no action" only when the module has been reviewed and no task is
  needed.
- Cross-reference existing architecture tasks instead of duplicating them.

Review progress:
- =system-lib.el=: reviewed 2026-05-03. No immediate action beyond the existing
  [#B] system-lib extraction task.
- =host-environment.el=: reviewed 2026-05-03. See child tasks below.
- =user-constants.el=: reviewed 2026-05-03. See child tasks below.
- =system-defaults.el=: reviewed 2026-05-03. See child tasks below.
- =keybindings.el=: reviewed during architecture pass. No new module-specific
  action beyond the load-order/keymap architecture tasks.
- =config-utilities.el=: reviewed 2026-05-03. No new module-specific action;
  profiling extraction is already tracked by [#B] "Build debug-profiling.el
  module".
- =early-init.el=: reviewed 2026-05-10. See child tasks below and the existing
  [#B] "Split early startup from package bootstrap" task.
- =init.el=: reviewed 2026-05-10. See child tasks below and the existing
  eager load-graph architecture tasks.

Completion review 2026-05-15:
- Re-read the parent =Module-by-module review and hardening= context and the
  adjacent architecture follow-up so this review stays module-specific.
- Re-checked all scoped files against the review protocol. Existing child
  tasks below still cover the actionable module findings for
  =user-constants.el=, =host-environment.el=, =system-defaults.el=, and
  =early-init.el=.
- =system-lib.el=, =keybindings.el=, =config-utilities.el=, and =init.el= do
  not need additional module-specific child tasks from this pass; remaining
  concerns are already tracked by the utility-consolidation, keymap
  registration, debug-profiling, and eager-load-graph architecture tasks.

**** 2026-05-25 Mon @ 19:12:02 -0500 Split path constants from filesystem init in user-constants.el

=(require 'user-constants)= used to create ~8 directories and ~10 org/calendar
files at load — the source of the stray =sync/org/= tree that appeared in the
repo during test runs. Both load-time forms are gone now; the path defconsts
stay pure, and init.el calls =cj/initialize-user-directories-and-files= on real
startup (guarded by =(unless noninteractive)=) so a bare require is
side-effect-free. Verified end-to-end: a require creates nothing, and the
interactive guard creates the backbone dirs and files. Landed in two commits on
the =refactor/user-constants-defer-fs-init= branch.

***** 2026-05-25 Mon @ 19:12:02 -0500 Extracted pure path definitions from startup writes

Removed the top-level calendar =dolist= and the top-level initializer call, and
folded gcal/pcal/dcal into =cj/initialize-user-directories-and-files=. init.el
now calls it right after the require, guarded by =(unless noninteractive)=.
Added =tests/test-user-constants.el= (loading creates nothing; the initializer
creates the configured paths) and updated the module header — top-level side
effects are now none and it's safe to load in tests.

***** 2026-05-25 Mon @ 19:12:02 -0500 Made initialization failures actionable

=cj/verify-or-create-dir=/=-file= took an optional =required= flag routed
through =cj/--report-path-failure=: required failures raise a prominent
=display-warning=, optional ones are logged. The initializer groups paths by
that split — required: the sync/org/roam dirs and the gcal/pcal/dcal stubs;
optional: the secondary dirs and content files. Chose a warning over a
=user-error= so a directory hiccup surfaces loudly without aborting init. Added
error-path tests for the optional-logs and required-warns behavior.

**** 2026-05-23 Sat @ 03:33:30 -0500 Fixed env-desktop-p doc and normalized the X predicates
Corrected =env-desktop-p='s docstring (it described a laptop; the function returns t for the desktop/no-battery case). Switched =env-x-p= from =(string= (window-system) "x")= to =(eq (window-system) 'x)= to match =env-x11-p='s style, and documented the difference: =env-x-p= is any X display incl. XWayland, =env-x11-p= is a real X11 session with no WAYLAND_DISPLAY. Behavior unchanged, existing display-predicate tests stay green. Fixed in 14ec32b2.

Left =cj/match-localtime-to-zoneinfo= caching alone — it was a "consider if this runs during startup" note, not an acceptance item, and it doesn't run at startup. File a separate task if it ever shows up in a profile.

**** 2026-05-25 Mon @ 16:59:37 -0500 Added system-defaults settings smoke tests

Added =tests/test-system-defaults.el= with three settings assertions the
existing files didn't cover: custom-file is redirected to a temp trashbin
(not the repo), backups land under =user-emacs-directory/backups=, and the
minibuffer GC hooks are wired onto the minibuffer hooks. The module's
functions were already covered by =test-system-defaults-functions.el= and the
=vc-follow-symlinks= default by its own file, so this stayed narrow to the
settings gap. Extracted the shared sandbox loader into
=tests/testutil-system-defaults.el= so both the new file and the
vc-follow-symlinks test use one copy. The backups test clears
=cj/backup-directory= first because it's a defvar that only recomputes when
unbound.

**** TODO [#B] Move package bootstrap policy out of =early-init.el= :refactor:

=early-init.el= currently handles performance/debug setup, package archive
construction, archive refresh policy, =use-package= installation, package
signature policy, and Unicode defaults. That makes early startup do network- and
package-manager-adjacent work before the regular module system exists.

This overlaps with the existing [#B] "Split early startup from package
bootstrap" task; keep the implementation there if that task is already active.
This foundation review finding is the module-level acceptance detail.

Expected outcome:
- =early-init.el= keeps only settings that must happen before normal init:
  startup GC/file-handler tuning, debug flag setup, native-comp workaround,
  =load-prefer-newer=, site-start suppression, and package startup suppression.
- Package archive setup, refresh/install policy, and =use-package= bootstrap
  live in a normal module or bootstrap helper that can be tested directly.
- Offline and missing-package states produce actionable errors without doing an
  unexpected package refresh during early startup.
- Existing local repo and ELPA mirror behavior is preserved.

Pitfalls:
- Do not break first-run bootstrap on a clean machine.
- Keep local repositories higher priority than online archives.
- Avoid prompting or refreshing archives during batch tests.

**** TODO [#B] Decide and test package signature policy

=early-init.el= sets =package-check-signature= to =nil= after package setup, with
an earlier commented emergency toggle for expired signatures. That may be
intentional for local mirrors, but it is security-sensitive enough to make the
policy explicit.

Expected outcome:
- Document when signatures should be disabled, if ever.
- Prefer signatures on for online archives unless a local-mirror workflow
  requires otherwise.
- If signatures stay disabled, add a clear comment explaining the trust model.
- Add a small test or validation helper around the computed package policy if
  package bootstrap is extracted.

**** 2026-05-16 Sat @ 02:34:22 -0500 Consolidated user-home-dir into early-init as canonical

Canonical defconst in =early-init.el= kept (the package-archive paths
need it during package bootstrap, before normal modules load).
=modules/user-constants.el= switched to a `defvar` with the identical
=(getenv "HOME")= expression and a comment explaining the pattern:
defvar is a no-op at runtime (early-init's defconst wins, defvar
doesn't reassign a bound symbol), but it lets the module load /
byte-compile standalone when early-init hasn't run.  Drift risk is
mitigated by both expressions being =(getenv "HOME")= literally; the
comment flags the requirement to keep them identical.

**** 2026-05-16 Sat @ 02:34:22 -0500 Dropped redundant autoload alongside compile-time require in system-defaults.el

Kept the =eval-when-compile= requires for =host-environment= and
=user-constants= (they silence free-variable / free-function warnings
during byte-compile in isolation) and dropped the
=(autoload 'env-bsd-p ...)= line — both modules are loaded earlier in
init.el at runtime, and the eval-when-compile already exposes
=env-bsd-p= to the byte-compiler.  Added a comment documenting the
chosen boundary.

**** 2026-05-16 Sat @ 02:34:22 -0500 Converted cj/debug-modules and cj/use-online-repos to defcustom

Both toggles now live as =defcustom= with explicit =:type= and
=:group 'cj=.  =cj/debug-modules='s type is the natural choice form:
either =t= (all modules) or a list of module symbols.
=cj/use-online-repos='s type is boolean.  Added a top-level
=(defgroup cj ...)= in early-init.el so the group exists for both,
plus the package-priority constants below it.

**** 2026-05-25 Mon @ 18:29:40 -0500 Made the Customize-save discard non-silent

Took the display-warning option. =cj/--warn-customize-discarded= advises
=custom-save-all= (the chokepoint both =customize-save-variable= and the
Customize "Save for Future Sessions" button funnel through) with a one-shot
=:before= warning that explains the edit won't persist and points at the Elisp
init files. The advice removes itself after firing, so it warns once per
session, and the body never runs at load, so startup stays quiet. Kept the
throwaway =custom-file= as-is. Test added in =tests/test-system-defaults.el=.

**** 2026-05-16 Sat @ 02:34:22 -0500 Named the package archive priorities in early-init.el

Nine =defconst= entries replace the magic numbers:
=cj/package-priority-localrepo= (200) for the project-pinned repo,
four =cj/package-priority-mirror-*= entries for the local ELPA
mirrors (125 / 120 / 115 / 100), four =cj/package-priority-online-*=
entries for the online archives (25 / 20 / 15 / 5).  A header comment
above the block explains the local-first ordering and the
gnu > nongnu > melpa > melpa-stable trust ranking within each tier.

**** 2026-05-16 Sat @ 02:34:22 -0500 Deleted dead world-clock block in chrono-tools.el

The 19-line commented-out =use-package time= block is gone.  The
=time-zones= use-package directly above it is the active replacement;
git history preserves the old config if anyone needs to dig it back up.

**** 2026-05-16 Sat @ 02:34:22 -0500 Added coverage for cj/tmr-select-sound-file with a pre-test refactor

The prefix-arg branch now delegates to =cj/tmr-reset-sound-to-default=
directly (single source for the reset path).  Extracted a pure helper
=cj/tmr--available-sound-files= so the directory scan is testable
without driving =completing-read=.  =tests/test-chrono-tools-tmr-sound.el=
covers Normal / Boundary / Error: available-sounds against a populated
dir, empty dir, missing dir; reset path; select with prefix-arg
(delegates to reset, no prompt); select normal (picks a file); select
boundary paths for empty dir, missing dir, cancel (empty completion).
9 tests, all green.

*** DOING [#B] Harden custom editing utility modules

Scope:
- =custom-buffer-file.el=
- =custom-case.el=
- =custom-comments.el=
- =custom-datetime.el=
- =custom-line-paragraph.el=
- =custom-counts.el=
- =custom-format.el=
- =custom-text-transform.el=
- =custom-ordering.el=
- =custom-text-enclose.el=
- =custom-whitespace.el=
- =external-open.el=
- =media-utils.el=

Review progress:
- Core =custom-*= text modules reviewed 2026-05-03. They have unusually strong
  direct ERT coverage compared with the rest of the config.
- =external-open.el= and =media-utils.el= reviewed 2026-05-03. See child tasks.
- =custom-buffer-file.el= reviewed 2026-05-03. See child tasks.

Completion review 2026-05-15:
- Re-checked the scoped custom editing utility modules and their test files.
- The pure editing modules remain well covered by focused ERT tests.
- Remaining actionable issues are already logged below: process-launch
  hardening and coverage for =external-open.el= / =media-utils.el=,
  destructive buffer/file keybinding policy, and explicit cross-module
  autoload/require boundaries.

**** TODO [#B] Harden external process launching in =external-open.el= and =media-utils.el= :refactor:

=external-open.el= and =media-utils.el= use shell command strings for launching
external applications:
- =cj/open-this-file-with= interpolates the user-supplied command into
  =call-process-shell-command=.
- =cj/media-play-it= builds a shell command for players and optional =yt-dlp=
  stream extraction.

This is mostly controlled local input, but it is still brittle: command paths
with spaces can fail, arguments are hard to reason about, and future URL/source
changes could create shell quoting bugs.

Expected outcome:
- Prefer =start-process= / =call-process= with argv lists where possible.
- If shell is required for command substitution, isolate and quote every
  untrusted value.
- Add tests around command construction for:
  - file paths with spaces and shell metacharacters,
  - URL strings with shell metacharacters,
  - configured player args,
  - missing executable errors.

Pitfalls:
- =cj/open-this-file-with= may intentionally accept "program plus args". If so,
  split the command deliberately or introduce separate program/args prompts.
- Some media players need different URL handling; preserve the existing
  =:needs-stream-url= behavior.

**** 2026-05-23 Sat @ 03:41:00 -0500 Added media-utils coverage; external-open already covered
=external-open= already had three test files (=test-external-open-commands.el=, =test-external-open-lib-command.el=, =test-external-open-lib-launcher-p.el=). =media-utils.el= had none, so I added =test-media-utils.el= (8 cases): player availability from =cj/media-players=, the play command-builder (direct vs yt-dlp -g stream wrap), and the missing-tool error paths for the player, =yt-dlp=, and =tsp=. All process/exec boundaries mocked. Added in the test-media-utils commit.

**** TODO [#B] Audit destructive buffer/file keybindings for confirmation policy

=cj/buffer-and-file-map= includes destructive operations under =C-; b=,
including delete file, erase buffer, clear top, clear bottom, and revert. Some
are intentionally fast, but this module is high blast radius.

Expected outcome:
- Decide which operations need confirmation when the buffer is modified or
  visiting a file.
- At minimum, document the intended policy in =custom-buffer-file.el=.
- Consider safer wrappers for =erase-buffer= and =revert-buffer= under the
  personal keymap.

**** 2026-05-24 Sun @ 14:43:13 -0500 Declared cross-module commands bound in custom keymaps

Byte-compiling =custom-ordering.el= and =custom-text-enclose.el= standalone warned "not known to be defined" for =cj/org-sort-by-todo-and-priority= (owned by org-config) and =change-inner=/=change-outer= (the change-inner package). Both work at runtime — org-config loads eagerly, and text-config autoloads change-inner via =use-package :commands= — so only the compiler needed telling; added =declare-function= for each (no autoload needed since the runtime autoload/eager-load already exists). =custom-buffer-file.el= byte-compiles clean already, so it needed no change. Commit =ad173a77=.

**** 2026-05-24 Sun @ 07:26:31 -0500 Extracted shared region-or-buffer bounds helper

The described docstring mismatch was already resolved: =custom-ordering.el='s =cj/--arrayify=/=cj/--unarrayify= now document an explicit =(start end)= contract accurately and are region-required by design. The remaining work was the enclose side, where append/prepend/indent/dedent each inlined the same region-or-buffer bounds block (four copies). Extracted =cj/--region-or-buffer-bounds= as the single source of that contract and routed all four through it (behavior unchanged; public-wrapper tests still pass). Each pair now has one clear, consistent, documented contract. New tests cover the helper (region / no-region / empty buffer). Commit =a7cc8948=.

**** 2026-05-16 Sat @ 02:47:15 -0500 Preserved trailing newlines in custom-ordering output

Both =cj/--arrayify= and =cj/--unarrayify= now detect a trailing
newline on the input region (via =string-suffix-p=) and re-append it
to the result.  Matches the pattern =custom-text-enclose.el= already
uses.  Docstrings updated to document the contract.

**** 2026-05-16 Sat @ 02:47:15 -0500 Guarded cj/duplicate-line-or-region against modes without comment syntax

=cj/duplicate-line-or-region= now signals a clear =user-error= when
=COMMENT= is non-nil but the current mode has no =comment-start=
(=fundamental-mode= and similar).  Docstring updated to document the
error.  Picks the "error out clearly" branch from the task body --
restricting the binding per-mode would be a larger refactor that
isn't justified for the silent-malformed-output blast radius.

**** 2026-05-16 Sat @ 02:47:15 -0500 Made external-open advice install explicit via cj/external-open-install-advice

Factored the =advice-remove= / =advice-add= pair into
=cj/external-open-install-advice= and called it once at the bottom
of the module.  Same idempotent shape (remove-then-add) but now the
intent is named.  Re-running the module updates the advice rather
than stacking it; if a future caller wants to opt out, they can
=advice-remove= the helper or skip calling it altogether.

**** 2026-05-16 Sat @ 02:47:15 -0500 Added cj/--validate-decoration-char across all six divider/border helpers

New top-level validator =cj/--validate-decoration-char= rejects
anything that isn't a printable single-character string and signals
=user-error=.  Wired into all six internal helpers:
=cj/--comment-inline-border=, =cj/--comment-simple-divider=,
=cj/--comment-padded-divider=, =cj/--comment-box=,
=cj/--comment-heavy-box=, =cj/--comment-block-banner=.  The five
nil-decoration ERT tests updated from =:type 'wrong-type-argument=
(the old crash signal from =string-to-char= on nil) to
=:type 'user-error=, since the guard now produces a clear message
instead of a deep crash.

**** 2026-05-23 Sat @ 03:38:30 -0500 Filled the remaining title-case edge gaps
=test-custom-case-title-case-region.el= already had 29 cases (empty region, unicode words, numbers, separators, colon resets, partial region). The named gaps that were missing — leading-quote and leading-paren handling, plus a caseless RTL first word — are now covered by three boundary tests (32 total). Added in 3841c59e.

**** 2026-05-16 Sat @ 02:47:15 -0500 Extracted cj/--require-spell-checker

Both =cj/flyspell-toggle= and =cj/flyspell-then-abbrev= now call
=cj/--require-spell-checker= instead of carrying their own copy of
the executable-find check.  The checker list lives in the new
defconst =cj/--spell-checker-executables=, so adding nuspell (or any
other checker) is a one-line edit.  Top-level =(require 'cl-lib)=
added since the new helper uses =cl-some=.

**** 2026-05-23 Sat @ 03:44:50 -0500 Covered flyspell-and-abbrev testable seams
Added =test-flyspell-and-abbrev.el= (8 cases): =cj/--require-spell-checker= (PATH gate, mocked), =cj/find-previous-flyspell-overlay= against synthetic overlays (closest-previous match, non-flyspell skipped, nil when none), and =cj/flyspell-on-for-buffer-type= (prog-mode -> flyspell-prog-mode, text-mode -> flyspell-mode). Left =cj/flyspell-then-abbrev= to manual testing — pinning its flyspell-UI orchestration would mean mocking flyspell internals rather than our logic. Added in the test-flyspell-abbrev commit.

*** 2026-06-12 Fri @ 07:14:11 -0500 Hardened UI and navigation modules

Scope:
- =ui-config.el=
- =ui-navigation.el=
- =ui-theme.el=
- =font-config.el=
- =modeline-config.el=
- =selection-framework.el=
- =mousetrap-mode.el=
- =popper-config.el=

Review progress:
- Reviewed 2026-05-03.
- =mousetrap-mode.el= has strong focused and integration tests.
- =modeline-config.el= has pure string-helper coverage, but not VC/runtime
  segment behavior.
- =font-config.el=, =ui-theme.el=, =selection-framework.el=, =ui-navigation.el=,
  and =popper-config.el= have little direct test coverage.

Completion review 2026-05-15:
- Re-checked the scoped UI/navigation modules and current tests.
- =mousetrap-mode.el=, =ui-navigation.el=, =ui-theme.el=,
  =selection-framework.el=, and selected modeline/UI helpers now have focused
  tests, but the font/modeline/popper runtime policy remains under-tested.
- Existing cleanup below covers the disabled =popper-config.el= load-graph
  issue; added a separate test-gap task for the remaining UI smoke coverage.

**** 2026-05-25 Mon @ 17:05:00 -0500 Added UI/navigation runtime smoke coverage

Added =tests/test-font-config.el= (4 tests): cj/font-installed-p returns t/nil
off find-font, and cj/apply-font-settings-to-frame is a no-op on a non-GUI
frame and applies the preset exactly once per frame (idempotent). find-font,
env-gui-p, and fontaine-set-preset are stubbed so the run stays headless, and
a skip-unless on the demanded packages keeps a bare checkout green.
font-config had zero direct coverage; this fills the gap the task named.

modeline-config was already well covered (string-cut-middle, string-truncate-p,
vc-cache, vc-cache-key, the flycheck segment, the recording indicator), so it
needed no net-new smoke tests. popper-config's no-op smoke test is gated on the
"Decide whether popper-config.el should exist while disabled" task and was
deferred there, since whether to write it depends on that keep/remove call.

Original scope:
- =font-config.el=: font fallback/daemon frame setup does not error when
  optional fonts or emoji packages are absent.
- =modeline-config.el=: runtime segment assembly handles missing VC/project
  data and does not signal in non-file buffers.
- =popper-config.el=: if the module remains in =init.el= while disabled, a
  smoke test should prove requiring it is an intentional no-op.

**** 2026-05-26 Tue @ 17:33:28 -0500 Removed popper-config.el (disabled no-op)
Deleted =modules/popper-config.el= and its =(require 'popper-config)= in =init.el= (commit 1cca84c5). It was =use-package :disabled t=, so use-package elided the whole form and it ran nothing while still sitting in the load graph. No test existed and none was needed. validate-modules passes and init loads clean. The config stays in git history if popper is ever wanted.

***** 2026-05-26 Tue @ 15:15:43 -0500 Decided: remove popper-config.el
Craig's call: remove it (quick, solo). It has been a disabled no-op in the load graph. Remaining action: drop =(require 'popper-config)= from =init.el= and delete =modules/popper-config.el= (and any test), then close this task.

**** 2026-05-16 Sat @ 02:55:14 -0500 Moved popper-mode activation from :init to :config

=popper-mode +1= and =popper-echo-mode +1= now live in the
=:config= block of =modules/popper-config.el='s use-package form.
=:disabled t= now actually disables the mode (=:config= is skipped
when disabled; =:init= still runs but it only sets the reference-
buffer list and the display-buffer-alist entry, both of which are
harmless no-ops when popper itself never loads).  Comment in the
module explains the split.

**** 2026-05-16 Sat @ 02:55:14 -0500 Made cj/modeline-vc-fetch fall back when vc-git--symbolic-ref is missing

The =require 'vc-git= now uses =nil 'noerror=, and the call to
=vc-git--symbolic-ref= is gated on =(fboundp ...)= so an Emacs
version that renames or removes the internal accessor just leaves
=branch= at =vc-working-revision='s output instead of crashing the
modeline render.  Added =ignore-errors= around the call too in case
the internal accessor signals on unusual inputs.

**** 2026-05-25 Mon @ 18:18:29 -0500 Theme-aware font label face in cj/display-available-fonts

Replaced the hardcoded =((:foreground "Light Blue" :weight bold))= label
face in =modules/font-config.el= with =(font-lock-keyword-face (:weight
bold))= so the family header follows theme contrast instead of being
unreadable on light themes. The Regular/Bold/Italic sample lines stay as-is
(they render in each font family on purpose).

=modules/font-config.el:266= hardcodes ="Light Blue"= and gray
foreground for font labels.  Switching themes (especially light
themes) makes the labels nearly unreadable.  Replace the literal
color with a face reference (=font-lock-keyword-face= or a face this
config owns) so the labels follow theme contrast.

**** 2026-05-25 Mon @ 18:18:29 -0500 Routed emoji fontset through per-frame hook in daemon mode

The emoji-fontset =(when (env-gui-p) (cond ...))= block in
=modules/font-config.el= ran once at load. In daemon mode =env-gui-p= is
nil at load (no GUI frame yet), so a later =emacsclient -c= frame inherited
no emoji fontset. Wrapped it in =cj/setup-emoji-fontset= (idempotent, GUI-
guarded) and, mirroring the fontaine pattern, added it to
=server-after-make-frame-hook= in daemon mode / ran it directly otherwise.
The all-the-icons install path already used the per-frame hook, so it was
left alone. Manual daemon TTY-then-GUI test added under "Manual testing and
validation" (batch can't drive it).

**** 2026-05-25 Mon @ 18:05:56 -0500 Cached mousetrap keymaps per profile

=mouse-trap--build-keymap= rebuilt the whole keymap on every major-mode hook.
Moved the build into =mouse-trap--build-keymap-1= and cached its result in
=mouse-trap--keymap-cache=, keyed on =(profile-name . allowed-categories)=, so
the same profile reuses the cached map and editing a profile's categories
changes the key and rebuilds. Sharing one keymap object across buffers is safe
since the map only binds disallowed events to =ignore= and is never mutated.
Added =mouse-trap--clear-keymap-cache=. Behavior is unchanged; 5 cache tests
plus the existing 66 mousetrap tests pass. Done by subagent, reviewed.

**** 2026-05-24 Sun @ 07:26:31 -0500 Keyed VC modeline cache on resolved truename

=cj/modeline-vc-cache-key= keyed on =(list file cj/modeline-vc-show-remote)=, so a symlink whose target moved (shared drives, CI workspaces) kept serving the old VC backend. Added =(file-truename file)= to the key — one stat per refresh, cheap next to the VC calls the cache avoids — so a re-pointed symlink produces a different key and refreshes. Tests cover truename inclusion, stability for an unchanged file, and a symlink whose target moves. Commit =9135298c=.

**** 2026-05-24 Sun @ 04:01:02 -0500 Verified C-s already advances isearch — non-bug, no change

The premise didn't hold on Emacs 30.2. Investigated in the live daemon: while isearch is active, =overriding-terminal-local-map= is =isearch-mode-map= and the effective =C-s= resolves to =isearch-repeat-forward=, not =cj/consult-line-or-repeat=. isearch installs its own map as an overriding map, so the global =C-s= binding can't shadow it during a search. =isearch-mode-map= already binds =C-s= to =isearch-repeat-forward= by default. Adding an explicit binding to the consult =:bind= block would only duplicate that default, so I left =selection-framework.el= unchanged.

**** 2026-05-16 Sat @ 02:55:14 -0500 Guarded cursor-color hook behind display-graphic-p (with daemon-mode catch)

Both the install (=add-hook= on =post-command-hook=) and the function
body now gate on =(display-graphic-p)=.  Batch and TTY runs short-
circuit cleanly: no per-command overhead, no =set-cursor-color= calls
on frames that don't have a cursor color.  A =server-after-make-frame-hook=
catches the daemon case where the first GUI frame is created after
=ui-config= loads -- it installs the hook lazily the first time a
GUI frame appears.

The two cursor-color test files
(=test-ui-config--buffer-cursor-state.el=,
=test-ui-cursor-color-integration.el=) stub =display-graphic-p= to
return t so the work body still runs in batch.

**** 2026-05-16 Sat @ 02:55:14 -0500 Deferred nerd-icons by dropping :demand t plus an after-load safety net

=(use-package nerd-icons :demand t ...)= flipped to =:defer t=.  The
=:config= block already wraps the advice + tint in lazy-on-load
semantics, so the advice now installs the first time nerd-icons
loads (typically when a feature module like =dashboard-icon-type=
or =dirvish-attributes= triggers a load).  An additional
=(with-eval-after-load 'nerd-icons ...)= block at module bottom
catches the "already-loaded when this module re-evaluates" case --
it checks =advice-member-p= so it doesn't stack the advice on every
re-eval.

*** DOING [#B] Harden Org workflow modules

Scope:
- =org-config.el=
- =org-agenda-config.el=
- =org-babel-config.el=
- =org-capture-config.el=
- =org-contacts-config.el=
- =org-drill-config.el=
- =org-export-config.el=
- =org-noter-config.el=
- =org-refile-config.el=
- =org-reveal-config.el=
- =org-roam-config.el=
- =org-webclipper.el=
- =calendar-sync.el=
- =hugo-config.el=
- =gloss-config.el=

Review progress:
- Reviewed 2026-05-03 at high level.
- =calendar-sync.el= has substantial focused coverage for parsing, recurrence,
  timezone conversion, event conversion, and regressions. The largest remaining
  risks are configuration/secrets, startup side effects, and process/network
  boundaries.
- =org-agenda-config.el= and =org-refile-config.el= now have useful cache tests,
  but the cache lifecycle and startup idle timers still deserve a design pass.
- =org-noter-config.el= already has an older [#B] workflow VERIFY task. Do not
  duplicate that work here.
- =hugo-config.el= and =org-reveal-config.el= have focused helper coverage.
- =gloss-config.el= is a thin package wrapper; no local unit-test target unless
  custom glue is added.
- Deeper pass 2026-05-10 added follow-up tasks for org-roam done hooks, drill
  file selection/package loading, Org export defaults, Babel templates, and
  contact/Mu4e boundaries.

Completion review 2026-05-15:
- Re-checked the scoped Org workflow modules and their test coverage.
- The broad parser/cache/helper areas now have useful focused tests, especially
  =calendar-sync.el=, agenda/refile helpers, org-roam helpers, org-noter, Hugo,
  reveal, and webclipper processing.
- Remaining issues are already logged below, including security-sensitive
  calendar config and Babel evaluation policy, cache lifecycle/timer behavior,
  org-roam destructive workflow guardrails, executable checks, capture-template
  smoke tests, and Org workflow ownership documentation.

**** 2026-05-23 Sat @ 04:18:44 -0500 Split personal calendar config out of calendar-sync.el
=calendar-sync.el= now defaults =calendar-sync-calendars= to nil and loads the real plists from =calendar-sync-private-config-file= (an ignored file), so the engine carries no private feed tokens in source. =calendar-sync-status= / =calendar-sync-start= report missing config without erroring, and agenda startup is unaffected (tests/test-calendar-sync-no-config-startup.el). Rotating the previously-committed feed URLs remains a manual credential action — tracked under the L2557 calendar-sync hardening finding.

**** 2026-06-12 Fri @ 07:14:11 -0500 Normalized Org agenda/refile cache lifecycle

All three children landed: shared cache helper extracted, idle timers gated, and directory-scan failures surfaced instead of hidden.

***** 2026-05-23 Sat @ 04:18:44 -0500 Extracted a shared cache helper
=cj-cache-lib.el= now provides =cj/cache-valid-p=, =cj/cache-building-p=, and =cj/cache-value-or-rebuild=, consumed by both =org-agenda-config.el= and =org-refile-config.el=; the contract is documented in =docs/specs/cache-helper-design-spec-implemented.org=. The agenda and refile public commands are unchanged.

***** 2026-05-24 Sun @ 07:26:31 -0500 Surfaced directory-scan failures instead of hiding/crashing

The refile scan caught =permission-denied= and silently dropped the dir, and crashed outright on a missing root (only permission-denied was caught, so a missing =code-dir=/=projects-dir= raised =file-missing= and aborted the build); the agenda build had the same missing-dir crash via =directory-files=. Extracted =cj/--org-refile-scan-dir= (warns + returns nil for missing/unreadable/permission-denied so the scan continues) and guarded the agenda scan the same way. Also fixed a latent bug found here: =org-refile-targets= was never declared special, so under =make compile= =cj/org-refile-in-file= let-bound it lexically and the scoped targets never reached =org-refile= — added =(defvar org-refile-targets)=. Tests cover the helper + the agenda missing-dir guard. Commit =12fb0108=.

***** 2026-05-23 Sat @ 04:18:44 -0500 Gated cache idle timers out of batch
Both cache builders' =run-with-idle-timer= calls are wrapped in =(unless noninteractive)= (=org-refile-config.el:105=, =org-agenda-config.el:203=), so requiring the modules in batch schedules nothing. =tests/test-architecture-startup-contracts.el= scans every module and asserts there are no unguarded top-level timer forms.

**** 2026-05-23 Sat @ 19:48:00 -0500 Made org-confirm-babel-evaluate default to t with a toggle

=org-babel-config.el= set =org-confirm-babel-evaluate= to nil globally, so every source block in every Org file (cloned repos, downloaded notes, web clips) ran without confirmation. Changed the default to =t= (confirm before running). Replaced the old =babel-confirm= command (which reported, and toggled only with a prefix arg) with =cj/org-babel-toggle-confirm=, a plain toggle bound to =C-; k= for flipping confirmation off in trusted files and back on. 3 ERT tests cover the toggle both directions plus the binding.

**** TODO [#B] Rebind babel-confirm toggle off =C-; k=

=cj/org-babel-toggle-confirm= landed on =C-; k= as a placeholder. Pick a permanent home — likely under an Org-specific prefix rather than the global =C-;= map.

Triggered by: 2026-05-23 org-confirm-babel-evaluate hardening.

**** 2026-05-24 Sun @ 14:43:13 -0500 Guarded move-branch-to-roam against data loss

The command cut the subtree from the source before writing the new roam file, so any failure in demote/format/write/db-sync lost the subtree with no rollback. Reordered to write and verify the file on disk before =org-cut-subtree=, so a failed write aborts with the source intact. Added a no-clobber guard (refuse an existing target file) and a confirmation prompt for large subtrees (>= =cj/move-org-branch-confirm-lines=, 30) or buffers with unsaved changes. Decided: leave the source buffer modified and undoable rather than auto-saving, so the move stays reversible. New test drives the write-failure-preserves-source invariant via an unwritable roam dir. Commit =5c0fa15d=.

**** 2026-05-25 Mon @ 18:29:40 -0500 Already done — clip URL/title scoped to dynamic bindings

Found this already shipped in =6dfc41af= ("refactor(webclipper): scope clip
URL/title to dynamic bindings", 2026-05-24). The temp vars =cj/--webclip-url= /
=cj/--webclip-title= are now =let=-bound around the org-capture call instead of
=setq='d and manually cleared, so they unwind on every exit path including a
=C-g= abort — which covers the "aborted captures clear temp state" outcome more
completely than a finalize hook would. The bookmarklet/org-protocol workflow is
unchanged. =tests/test-org-webclipper-commands.el= already covers the
leaves-no-stale-state and aborted-capture-clears-state cases. No new work needed.

**** 2026-05-25 Mon @ 17:51:17 -0500 Guarded external-tool assumptions in Org export/publishing

Added command-time guards to four export/publishing commands so a missing tool
fails with a user-error that names it, instead of an opaque process error (or,
for reveal.js, a silently broken presentation):
- =org-export-config.el=: zathura check in my/org-pandoc-export-to-pdf-and-open.
- =hugo-config.el=: hugo binary check in cj/hugo-preview, and the platform
  file-manager opener check in cj/hugo-open-blog-dir-external.
- =org-reveal-config.el=: extracted =cj/--reveal-ensure-root= (checks the local
  reveal.js clone, points at scripts/setup-reveal.sh), called from
  cj/reveal-export and cj/reveal-preview-start.
- =org-webclipper.el=: pandoc check in cj/org-protocol-webclip-handler, the
  single path that shells out to pandoc via org-web-tools.

All checks run at command time, not load, so startup stays quiet. Each guard
has a user-error test; existing happy-path tests now stub the lookups. Things
deliberately not guarded: hugo-publish (magit, internal), the preview filter
(browse-url, internal), hugo-export-post (ox-hugo, Elisp). Done with four
parallel implementation agents, reviewed individually; full suite green.

**** 2026-05-16 Sat @ 03:44:45 -0500 Guarded org-roam completed-task hook with cj/--org-roam-should-copy-completed-task-p

=org-roam-config.el= adds a global =org-after-todo-state-change-hook= that
copies newly completed tasks to today's org-roam journal. The hook assumes the
current Org buffer is visiting a file:

- It calls =(buffer-file-name)= and passes the result to =string=.
- =cj/org-roam-copy-todo-to-today= later compares =file-truename= of the daily
  file and the current buffer file.

That can error in capture buffers, indirect buffers, temporary Org buffers, or
other fileless Org workflows.

Expected outcome:
- Extract a predicate for "should copy this completed task to today's journal".
- Skip fileless buffers, calendar sync files, aborted capture buffers, and tasks
  already in the target daily file.
- Keep the normal completed-task journal workflow unchanged.
- Add tests for fileless buffers, =gcal-file=, already-daily buffers, and a
  normal project/todo buffer.

**** 2026-05-24 Sun @ 04:30:14 -0500 Shared one validated drill-file selector

org-capture-config.el and org-drill-config.el each scanned =drill-dir= with an inline =directory-files= call, so a missing/empty/unreadable dir surfaced as a low-level error or an empty =completing-read= depending on which command ran. Added =cj/--drill-files-or-error=, the single validated entry point: clear =user-error= when the dir is missing, unreadable, or has no drill files; otherwise the list. =cj/--drill-pick-file= and both drill capture templates route through it; the pure =cj/--drill-files-in= primitive and its tests are unchanged. Tests cover missing/empty/non-org/normal. Commit =49038c41=.

**** 2026-05-24 Sun @ 14:43:13 -0500 Removed contradictory org-export-with-tasks default

=org-export-config.el= set =org-export-with-tasks= twice (=("TODO")= then =nil=); the final =nil= won but the stale first line + comment contradicted it. Removed the leftover. =nil= (export no tasks) is the deliberate default — it was already winning, its comment matches, and it sits with the adjacent "without tags / section numbers by default" settings. Added a smoke test that fires the deferred =ox= :config and pins the value to =nil=. Commit =94ef5242=.

**** 2026-05-23 Sat @ 03:48:50 -0500 Fixed java structure-template typo and pinned the aliases
=("java" . "src javas")= expanded to a bogus =#+begin_src javas=; corrected it to =src java=. Added =test-org-babel-config-structure-templates.el=, which requires the module then org-tempo (firing the deferred :config) and asserts =bash=, =zsh=, =el=, =py=, =json=, =yaml=, =java= each map to the intended src language. Fixed in the org-babel commit.

**** TODO [#B] Make org-contacts/Mu4e boundaries explicit :refactor:

=org-contacts-config.el= defines helpers that call Mu4e functions when the
current major mode is a Mu4e mode, and the =use-package org-contacts= block is
=:after (org mu4e)= while also requiring =mu4e= inside =:config=. This works in
the current eager setup, but the ownership boundary is unclear now that
=mu4e-org-contacts-integration.el= exists.

Expected outcome:
- Decide whether contact capture-from-email behavior belongs in
  =org-contacts-config.el= or the Mu4e integration modules.
- Add =declare-function= / autoloads or move Mu4e-specific code behind
  =with-eval-after-load 'mu4e=.
- Keep plain Org contact commands usable on systems without Mu4e loaded.
- Add a smoke test for loading =org-contacts-config.el= without Mu4e stubs if
  practical.

**** TODO [#B] Add an Org workflow health check command :feature:solo:

Several Org workflow modules depend on personal paths, optional external tools,
and local package checkouts. Failures currently show up at command time in
different ways, depending on which module hits the missing dependency first.

Recommended improvement:
- Add a lightweight =cj/org-workflow-doctor= command that checks the main Org
  workflow prerequisites without mutating user data.
- Report status for core files/directories: =org-dir=, =roam-dir=, =drill-dir=,
  =contacts-file=, =webclipped-file=, =cj/hugo-content-org-dir=, and
  =cj/reveal-root=.
- Report optional executable/package availability for Pandoc/org-web-tools,
  Hugo, reveal.js, org-drill, org-roam, and org-noter.
- Keep startup quiet; run this only on demand.
- Make the checker return structured data so it can be unit-tested and displayed
  either in Messages or a buffer.

**** 2026-05-24 Sun @ 14:43:13 -0500 Added capture-template key + target smoke tests

New =test-org-capture-templates-integrity.el= loads the cleanly-loadable capture modules (=org-capture-config=, =quick-video-capture=, =org-contacts-config=), applies their lazy additions, and asserts no two templates share a dispatch key and that every symbol-valued file target resolves to a non-empty path string. Literal-string targets (the video template's no-save =(file "")=) and lambda targets (drill file pickers) are excluded. Webclipper templates need org-web-tools at registration time, so they stay covered by their own test rather than this batch smoke test. Mutation-checked that the uniqueness assertion flags a duplicate key. Commit =2e3905c7=.

**** TODO [#B] Document Org workflow module ownership and load boundaries :refactor:solo:

The Org workflow is spread across many modules with overlapping responsibilities:
capture templates, keymaps, org-protocol handlers, refile/agenda target
construction, roam notes, publishing, and document annotation. The code is
usable, but future load-order work will be easier with explicit ownership notes.

Recommended improvement:
- Add a short design note under =docs/design/= that maps each Org module to the
  behavior it owns.
- Call out which modules may mutate global Org variables, capture templates,
  keymaps, and protocol handlers.
- Define which modules should be safe to load in batch mode and which are
  allowed to start timers or require interactive packages.
- Link this note from the Org workflow review task and the broader load-graph
  refactor.

**** 2026-05-16 Sat @ 03:44:45 -0500 Removed duplicate org-protocol-protocol-alist registration in cj/webclipper-ensure-initialized

The =webclip= protocol handler is registered twice:
=modules/org-webclipper.el:72-76= inside =cj/webclipper-ensure-initialized=
(unconditional =add-to-list=) and =:207-214= inside a
=with-eval-after-load 'org-protocol= block (=unless (assoc ...)= guard).
=add-to-list= uses =equal= membership so the two are effectively
idempotent, but maintaining two registration paths invites drift if
the alist entry shape ever changes.  Pick one site -- the
=with-eval-after-load= block is the more robust location -- and
remove the other.

**** 2026-05-16 Sat @ 03:44:45 -0500 Validated :url and :title in cj/org-protocol-webclip before stashing

=modules/org-webclipper.el:124-125= extracts =:url= and =:title= from
the incoming protocol plist with no type or nil check.  An unexpected
plist shape silently sets the globals to nil, and downstream code
fails inside the capture handler with confusing messages.  Guard with
=(unless (and (stringp url) (not (string-empty-p url))) (user-error ...))=
before stashing.

**** 2026-05-24 Sun @ 07:26:31 -0500 Scoped webclip URL/title to dynamic bindings

The protocol handler =setq= globals =cj/webclip-current-url= / =cj/webclip-current-title= that the "W" template and handler read (and cleared), so an aborted/erroring capture left stale state for the next clip. Renamed to =cj/--webclip-url= / =cj/--webclip-title= and =let=-bind them around the =org-capture= call: the template =%(identity ...)= forms and the handler run within that dynamic extent, and an abort/error unwinds the binding automatically — no stale state, no manual clear. Mirrors the quick-video-capture fix. Tests updated to the new contract (visible-during-capture, nothing-left-after, aborted-leaves-nothing). Commit =6dfc41af=.

**** 2026-05-16 Sat @ 03:44:45 -0500 Declared cross-module free vars in mu4e-org-contacts-integration.el

The module reads =contacts-file= (defined in =user-constants.el=) and
calls =cj/get-all-contact-emails= (defined in =org-contacts-config.el=)
without any forward declaration at the top of the file.  Byte-compile
in isolation warns about both as free variables / unknown functions.
Add =(eval-when-compile (defvar contacts-file))= and
=(declare-function cj/get-all-contact-emails "org-contacts-config")=
near the existing requires so the compile is clean and the
cross-module dependency is explicit at the top of the file.

**** 2026-05-25 Mon @ 17:10:47 -0500 Added mu4e org-contacts completion coverage

Added =tests/test-mu4e-org-contacts-integration.el= (10 tests). The capf
(cj/org-contacts-completion-at-point) is checked for the header-field and
compose-mode gating both ways, the bounds/table it returns when contacts
exist, and the empty-contacts case. TAB (cj/mu4e-org-contacts-tab-complete)
is checked across all three branches: completion-at-point in a header,
org-cycle in the org-msg body, indent elsewhere. Comma completion and the
direct-insert no-op-outside-header path round it out. mail-abbrev-in-expansion-header-p,
the mode actions, and cj/get-all-contact-emails are stubbed, so the run is
headless with no mu4e/org-contacts dependency.

*** DOING [#B] Harden programming workflow modules

Scope:
- =prog-c.el=
- =prog-general.el=
- =prog-go.el=
- =prog-json.el=
- =prog-lisp.el=
- =prog-lsp.el=
- =prog-python.el=
- =prog-shell.el=
- =prog-training.el=
- =prog-webdev.el=
- =prog-yaml.el=
- =coverage-core.el=
- =coverage-elisp.el=
- =test-runner.el=
- =vc-config.el=
- =keyboard-compat.el=
- =dev-fkeys.el=

Review progress:
- Reviewed 2026-05-03 at high level.
- =dev-fkeys.el= reviewed 2026-05-03 after local edits settled. The focused
  dev-fkeys test set passed: 22 test files, 163 ERT tests.
- =coverage-core.el= / =coverage-elisp.el= have strong pure-helper tests.
- Language formatter wiring is covered for Python, Go, shell, webdev, JSON, and
  YAML.
- =test-runner.el= has direct tests, but project-scoping is still a design gap.

Completion review 2026-05-15:
- Re-checked the scoped programming workflow modules and current tests.
- =dev-fkeys.el=, coverage modules, formatter wiring, keyboard compatibility,
  and test-runner helpers have meaningful focused coverage.
- Remaining issues are logged below: F4 project capability classification,
  LSP ownership and smoke coverage, tree-sitter auto-install policy, Git clone
  process handling, shell-script executable policy, and formatter process
  boundaries.

**** 2026-05-25 Mon @ 17:35:02 -0500 Added prog-lisp smoke coverage; assessed the other two

Added =tests/test-prog-lisp.el= (4 tests) covering the config prog-lisp owns
directly: cj/elisp-setup and cj/common-lisp-setup are each registered on their
mode hook and apply the right buffer locals (4-space/no-tabs/fill-120 for
elisp, 2-space/fill-100 for Common Lisp). The module loads with use-package
stubbed to a no-op, so nothing installs or downloads in batch.

=prog-training.el= got no test: it's entirely deferred use-package config with
no top-level surface, and its only owned settings (leetcode language/dir) live
in a deferred =:config= that would make the test package-dependent for no real
value. Forcing a test there would be coverage theater.

=prog-general.el= is deferred: it's the one of the three that touches LSP and
tree-sitter, and the task itself says to wait for the LSP/tree-sitter policy
tasks to land before fixing its assertions. Its smoke coverage rides with those.

**** TODO [#B] Revisit F4 project classification vs actual project capabilities

=dev-fkeys.el= classifies a project as =interpreted= if it has
=pyproject.toml=, =requirements.txt=, =Pipfile=, or =package.json=, even when it
also has a =Makefile=. That intentionally keeps Python/Node projects on a
Run-only F4 menu, but it also hides useful Compile/Clean options for projects
where =Makefile=, =package.json= scripts, or Projectile cached commands provide
real build/test tasks.

Expected outcome:
- Decide whether F4 should classify by language family or by available
  capabilities.
- Consider deriving candidates from Projectile's known compile/run/test commands
  first, then falling back to markers.
- Keep the current "interpreted markers win" behavior only if that remains the
  intentional UX after trying it in mixed Python/Node projects.

**** TODO [#B] Consolidate LSP ownership across programming modules :refactor:

LSP setup is currently split across =prog-general.el=, =prog-lsp.el=, and each
language module. There are multiple =use-package lsp-mode= forms and some
conflicting defaults:
- =prog-general.el= enables snippets/UI doc/sideline behavior.
- =prog-lsp.el= disables snippets/UI doc/sideline-heavy behavior.
- Python, Go, shell, C, and webdev modules both call =lsp-deferred= from local
  setup functions and add package hooks that call =lsp-deferred= again.

This probably works because lsp-mode is defensive, but it makes the final
runtime policy hard to predict.

***** TODO [#B] Make =prog-lsp.el= the single owner of generic LSP policy :refactor:

Expected outcome:
- Move generic =lsp-mode= and =lsp-ui= defaults out of =prog-general.el=.
- Keep language-specific server variables in language modules.
- Keep one hook path per language for starting LSP.
- Preserve the remote-file guard.

Pitfalls:
- =lsp-pyright= may still need a language-specific hook to load before LSP
  starts.
- Do not accidentally re-enable UI/doc/sideline behavior that was explicitly
  disabled for performance.

***** 2026-06-25 Thu @ 01:53:48 -0400 Added the LSP config-resolution smoke test
=tests/test-prog-lsp.el= (5 ERT tests) pins prog-lsp's load-time invariants: =lsp-enable-remote= stays nil (no auto-start on TRAMP files), the file-watch-ignore defaults live in one idempotent helper (=cj/lsp--add-file-watch-ignored-extras=), the eldoc provider is stripped from the global hook, and no mode holds a duplicate =lsp-deferred= entry. Tests the top-level =:init= + helper surface rather than the =:config= defaults, which defer to lsp-mode's own load under =make test= (the no-package-initialize constraint). Hit and fixed the lexical-binding special-var trap on =lsp-file-watch-ignored-directories= in the test.

**** TODO [#B] Gate tree-sitter grammar auto-install behind an explicit policy

=prog-general.el= sets =treesit-auto-install= to =t=. That means opening a file
can trigger grammar download/build/install behavior. This is convenient on a
fresh machine, but it is a startup/network/build side effect in normal editing
and batch contexts.

Expected outcome:
- Prefer ='prompt= or a custom command such as =cj/install-treesit-grammars=.
- Batch/test startup should never auto-install grammars.
- Document the intentional bootstrap path for a new machine.

Originally meant to coordinate with the [#A] Python tree-sitter predicate
syntax issue.  That one resolved upstream on 2026-05-14 (see =docs/python-
treesit-predicate-mismatch.txt= RESOLVED footer), so this task no longer
depends on it.

**** 2026-05-24 Sun @ 04:30:14 -0500 Hardened clipboard git-clone process and path handling

=cj/git-clone-clipboard-url= shelled out via =shell-command= and derived the dir with =file-name-nondirectory=, which mishandled scp-style SSH with no slash (=git@host:repo.git= → =git@host:repo=) and silently did nothing on a failed clone. Now clones as a direct =git= process (=call-process=, no shell) with =clone -- url dir= (so a =-=-leading URL can't be read as a flag); the destination comes from =cj/--git-clone-dir-name= (last component split on =/= and =:=, handling HTTPS, scp/ssh:// SSH, local paths); validates non-empty clipboard + writable target dir + non-existing destination; surfaces a non-zero git exit as a =user-error= with the =*git-clone*= output. Tests cover the deriver across schemes + empty-clipboard + clone-failure. Commit =35e4d701=.

**** TODO [#B] Decide whether auto-executable shell scripts should be opt-in

=prog-shell.el= adds a global =after-save-hook= that sets executable bits on any
saved file with a shebang. This is convenient, but it silently changes file
modes for every buffer in the session.

Expected outcome:
- Decide whether this should remain global, be limited to shell/script modes, or
  prompt the first time per file.
- Preserve the fast path for real scripts.
- Keep the existing =cj/make-script-executable= tests updated for the chosen
  policy.

**** 2026-05-25 Mon @ 18:05:56 -0500 Moved JSON/YAML/webdev formatters to argv process calls

Replaced =shell-command-on-region= with =call-process-region= (explicit program
+ argv, no shell) in cj/json-format-buffer (jq), cj/yaml-format-buffer
(prettier), and cj/webdev-format-buffer (prettier). The webdev path dropped its
=shell-quote-argument= once the filename became a plain argv element. Point
preservation is unchanged. One deliberate, tested improvement: the old code
clobbered the buffer with the formatter's error text on a non-zero exit; the new
per-module =cj/--<lang>-format-region= helper captures output, checks the exit
code, replaces only on success, and otherwise raises a user-error with stderr.
Kept a small helper in each of the three modules rather than one shared one,
since they share no module short of system-lib. Added argv-invocation and
no-clobber tests per formatter; existing wiring tests stay green. Done by
subagent, reviewed.

**** 2026-05-16 Sat @ 03:54:56 -0500 Added cj/executable-find-or-warn checks for prettier and pyright at load time

=modules/prog-webdev.el:34-40= declares =prettier-path= and
=modules/prog-python.el:33-40= declares =pyright-path= as string
literals.  No validation at module load means a missing executable
surfaces only at first use -- format-on-save fires, then errors
mid-edit, then the user has to discover why.  Wrap with
=cj/executable-find-or-warn= (already in =system-lib.el=) at module
load time so the missing dependency is reported up front.

**** 2026-05-16 Sat @ 03:54:56 -0500 Documented keyboard-compat hook idempotence (already correct)

=modules/keyboard-compat.el:169-174= adds the frame-setup hook
unconditionally.  If the module is required twice (e.g. via two
=eval-after-load= chains in different load orders), the hook runs
twice per new frame and installs duplicate =key-translation-map=
entries.  Wrap the =add-hook= in a guard, or use a named function
and rely on =add-hook='s own duplicate-check.

**** 2026-05-16 Sat @ 03:54:56 -0500 Wired F6 TypeScript clause to npx vitest|jest

=modules/dev-fkeys.el:261-269= maps =tsx= to =typescript= in the
language detection table.  =modules/dev-fkeys.el:347-349=
(=cj/--f6-test-runner-cmd-for=) has no clause for =typescript= --
the catch-all =(_)= returns nil, so F6 errors instead of routing to
a real runner.  Either add a =typescript= → =jest=/=vitest= clause
or remove the =tsx= mapping until the runner side is implemented.

**** 2026-05-16 Sat @ 03:54:56 -0500 Fixed prog-lsp eldoc-provider removal to act on the global hook

=modules/prog-lsp.el:51-54,76= attaches
=cj/lsp--remove-eldoc-provider= globally to =lsp-managed-mode-hook=
but the removal it performs uses =(remove-hook ... t)= -- a
buffer-local removal.  The first LSP buffer activates the hook,
which removes the provider for that buffer.  Subsequent LSP buffers
still inherit the global default because the hook itself never
re-fires the buffer-local removal in their context.  Either make
the hook itself buffer-local-friendly (add it inside
=lsp-managed-mode-hook= per-buffer) or remove from the global
provider list once instead of per-buffer.

**** 2026-05-16 Sat @ 03:54:56 -0500 Externalized LanguageTool script path via user-emacs-directory

=modules/flycheck-config.el:69= hardcodes
=~/.emacs.d/scripts/languagetool-flycheck= as the LanguageTool wrapper.
Users running from a non-standard =user-emacs-directory= (or anyone
auditing the module against a future package) get a broken checker.
Replace with =(expand-file-name "scripts/languagetool-flycheck"
user-emacs-directory)= or a defcustom.

**** 2026-05-16 Sat @ 03:54:56 -0500 Replaced hardcoded Zathura viewer with executable-find candidate list

=modules/latex-config.el:28= sets the LaTeX viewer to =zathura=
unconditionally.  macOS / Windows users and anyone who prefers a
different PDF viewer lose document review without explanation.
Resolve via =executable-find= over a candidate list (=zathura=,
=evince=, =okular=, =Preview.app= via =open=, =SumatraPDF.exe=) and
fall back to =pdf-tools=.

**** 2026-05-15 Fri @ 18:49:24 -0500 Fixed abbrev-mode no-arg toggle in =cj/prose-helpers-on=

Replaced the =(if (not (abbrev-mode)) (abbrev-mode))= shape with
=(unless (bound-and-true-p abbrev-mode) (abbrev-mode 1))= and the same
for =flycheck-mode= in =modules/flycheck-config.el:36-42=.  Dropped
"flyspell" from the docstring (the commented-out
=cj/flyspell-on-for-buffer-type= line had been gone for a while; the
docstring was lying) and removed the stale comment marker.

Added =tests/test-flycheck-config-prose-helpers-on.el= -- 4 tests
covering Normal (both modes off -> each enabled once with a positive
arg) and Boundary (both on -> no-op; each mixed state -> only the off
one enabled).  The "both on -> no-op" assertion is the regression
guard for the no-arg toggle shape: it would record a =(nil)= call list
under the bug and a =()= call list under the fix.

Test infra needed an explicit =(defvar abbrev-mode)= /
=(defvar flycheck-mode)= at the top of the test file: with
=lexical-binding: t= and flycheck loaded =:defer t=, =let= on the
flycheck-mode symbol creates a lexical-only binding the production
code's =bound-and-true-p= can't see; declaring both as special makes
=let= dynamic and the test stable.

Full suite: =make test= exits 0; 468 lines of output with =ALL UNIT
TESTS PASSED= banner; no regressions.

*** DOING [#B] Harden integrations and application modules

Scope:
- AI/rest: =ai-config.el=, =ai-conversations.el=, =restclient-config.el=
- Mail/chat/social: =mail-config.el=, =mu4e-*.el=, =slack-config.el=,
  =erc-config.el=, =elfeed-config.el=, =eww-config.el=
- File/media/apps: =dirvish-config.el=, =dwim-shell-config.el=, =pdf-config.el=,
  =calibredb-epub-config.el=, =music-config.el=, =quick-video-capture.el=,
  =video-audio-recording.el=, =transcription-config.el=
- Utilities/apps: =auth-config.el=, =browser-config.el=, =dashboard-config.el=,
  =help-config.el=, =help-utils.el=, =jumper.el=, =keyboard-macros.el=,
  =local-repository.el=, =lorem-optimum.el=, =reconcile-open-repos.el=,
  =show-kill-ring.el=, =system-commands.el=, =system-utils.el=,
  =tramp-config.el=, =undead-buffers.el=, =weather-config.el=, =wrap-up.el=

Review progress:
- Reviewed 2026-05-03 at high level by direct reads plus risky-pattern search.
- Recording/transcription and music modules have much stronger coverage than
  most application wrappers.
- Existing coverage audit already tracks =ai-conversations=, =quick-video-capture=,
  =dashboard-config=, =mail-config=, =show-kill-ring=, =system-commands=, and
  =wrap-up= as high-value test targets.

Completion review 2026-05-15:
- Re-checked the scoped integration/application modules with risky-pattern and
  test-coverage searches.
- Many integration modules now have focused tests, including AI config,
  restclient, mail helpers, Slack commands, Dirvish helpers, music,
  recording/transcription, system commands, browser/help/jumper/reconcile, and
  undead buffer helpers.
- Remaining issues are already logged below, especially system command safety,
  REST key persistence, mail privacy/lifecycle policy, quick-video timers and
  temp state, shell-heavy dwim/recording command hardening, AI conversation
  persistence coverage, calendar operational behavior, Dirvish dependency/path
  hardening, EWW/Elfeed network helpers, and Slack which-key registration.

**** 2026-05-24 Sun @ 04:15:36 -0500 Made Emacs restart and destructive confirms defensive

Restart-Emacs scheduled an unconditional =kill-emacs= one second after firing the systemctl restart, so a missing or failed service killed the session with nothing to replace it. Restart now guards on =(daemonp)= and a present =emacs.service= (new =cj/system-cmd--emacs-service-available-p= via =systemctl --user cat=) before doing anything, and drops the separate =kill-emacs= — =systemctl restart= cycles the daemon itself, so a failed restart leaves the current Emacs alive. Shutdown and reboot moved to a strong =yes-or-no-p= confirm (a stray RET/space on the old quick prompt could power off the machine); logout and suspend keep the quick confirm since they are recoverable. Tests cover service detection, both restart guards, and the strong-confirm paths with system primitives stubbed. Commit =f1dbec16=.

Not done: the detached restart+reconnect (=nohup sh -c '... && emacsclient -c'=) may still race systemd's cgroup teardown of =emacs.service= before =emacsclient -c= runs. Couldn't verify from here without cycling the live daemon — eyeball the reconnect on the next real restart.

**** 2026-05-23 Sat @ 19:01:53 -0500 Removed SkyFi key-injection feature from restclient-config

Resolved by removing the feature rather than hardening it. =cj/restclient-skyfi-buffer= opened =data/skyfi-api.rest= in a file-visiting buffer and rewrote the =:skyfi-key= line with the real key from authinfo, so an accidental save would persist the key to local disk (the file was gitignored and never tracked, so no repo/public-mirror exposure — local plaintext only). Deleted =cj/skyfi-api-key=, =cj/restclient--inject-skyfi-key=, =cj/restclient-skyfi-buffer=, the =C-; R s= binding, the two SkyFi test files, and the local =data/skyfi-api.rest= template. Generic restclient (=C-; R n=, =C-; R o=, restclient/restclient-jq) kept.

**** TODO [#B] Reconcile mail image/privacy settings

=mail-config.el= documents blocked remote images and sets
=gnus-blocked-images=, but later enables both =mu4e-show-images= and
=mu4e-view-show-images=. The interactive toggle changes =gnus-blocked-images=
buffer-locally, so the final privacy behavior is hard to reason about without
manual testing against real HTML messages.

Expected outcome:
- Decide the default policy for embedded images versus remote HTTP images.
- Make the toggle report the effective state in the current mu4e view buffer.
- Add a short manual checklist or mocked test for the variables that control
  remote image display.

**** 2026-05-23 Sat @ 03:52:00 -0500 Set compose buffers to kill on exit, both composers
First clarified the ownership (dd671f8c): the org-msg comment "always kill buffers on exit" was backwards — org-msg set =nil= (keep), which won over mu4e's =t= because org-msg-mode runs in every compose buffer. Craig then chose to kill compose buffers on exit, so I set the org-msg value to =t= as well (82978c79). Both mu4e and org-msg now kill the buffer on send/exit, so HTML drafts don't linger.

**** 2026-05-24 Sun @ 07:26:31 -0500 Dropped startup timers for lazy protocol init

=quick-video-capture.el= scheduled an =after-init-hook= idle timer + a 2s fallback =run-with-timer= to call setup, which required org-protocol/capture and registered both the protocol handler and the capture template at every startup. Split the concerns like =org-webclipper.el=: the org-protocol handler registers in a =with-eval-after-load 'org-protocol= block (lightweight =add-to-list=, in place whenever org-protocol loads — org-config requires it at startup), and =cj/setup-video-download= now registers only the capture template lazily (first capture or first protocol call). Both timers gone. Tests pin that setup registers the template idempotently and no longer touches the protocol alist; verified in a live daemon that the protocol registers on load. Commit =bc965275=.

**** 2026-05-24 Sun @ 04:30:14 -0500 Scoped video-capture URL to a dynamic binding

The protocol handler =setq= a global =cj/video-download-current-url= and the capture handler read/cleared it, so an aborted or erroring capture left the stale URL for the next manual capture. Renamed to =cj/--video-download-url= and =let=-bind it around the =org-capture= call instead of mutating a global: the binding lives only for the capture's dynamic extent, so the handler sees the URL while the capture runs and an abort/error unwinds it automatically — no stale state, no manual clear. Manual invocation still prompts. Tests cover bound-URL download, manual prompt, empty-URL error, URL-visible-during-capture, and aborted-capture-leaves-nothing. Commit =b26b74cb=.

Note: the sibling =org-webclipper.el= still uses the same global-mutation pattern (=cj/webclip-current-url= / =title=); a separate =:solo:= task tracks that.

**** 2026-06-12 Fri @ 07:14:11 -0500 Audited shell-command-heavy recording and dwim-shell workflows

=video-audio-recording.el= and =dwim-shell-config.el= are intentionally close to
the shell: pactl/ffmpeg/qpdf/7z/tesseract/media conversion commands are the
point. They also have the highest process and quoting surface in the config.

Expected outcome:
- Keep the current workflows, but catalog which commands accept filenames,
  URLs, passwords, or free-form user input.
- Prefer argv process APIs for commands that do not require a shell.
- For commands that must use shell templates, document which placeholders are
  safely quoted by =dwim-shell-command= and add focused tests around password
  temp-file cleanup.

***** 2026-05-23 Sat @ 19:11:30 -0500 Fixed async password temp-file lifetime in dwim-shell

The four password commands (PDF protect/unprotect, remove-zip-encryption, create-encrypted-zip) deleted the password temp file in =unwind-protect= the instant the async command launched, so =qpdf=/=7z= could start after the file was gone. Extracted =cj/dwim-shell--run-with-password-file= + =cj/dwim-shell--password-cleanup-callback=: the temp file (mode 600) is now deleted from an =:on-completion= callback that fires after the process exits (success or failure), with the synchronous =unwind-protect= kept only as a pre-launch-failure backstop. Rewrote all four commands onto the helper. 5 ERT tests cover the cleanup callback (success/error/missing-file) and the runner (writes 600 file + defers cleanup; cleans up on launch failure). qpdf already passes the password via =--password-file= (out of argv); the 7z argv exposure is split into its own follow-up below.

***** 2026-05-24 Sun @ 04:20:31 -0500 Accepted the brief 7z password-on-argv exposure, documented it

Investigated whether 7z could take the password off argv. It can't: 7-Zip 26.01 reads the password only from its controlling TTY, not stdin or a file. Verified empirically — =printf pw | 7z a -p ...= silently created an archive with an *empty* password (the piped value never reaches it), and a round-trip with the same password failed. So the password must go on argv via =$(cat tempfile)= and is briefly visible in the process list while 7z runs.

Craig's call (2026-05-24): accept the exposure rather than switch off the .7z format. On a single-user workstation, for a short-lived process, with the password already kept out of shell history by the mode-600 temp file, the residual exposure is acceptable. The gpg-wrapped-tar alternative would close it but change the archive format and decrypt workflow. Recorded the tradeoff in both function docstrings in =dwim-shell-config.el= so the decision is visible at the call site, not just here.

***** 2026-05-23 Sat @ 19:18:00 -0500 Quoted/validated user-controlled dwim-shell inputs

Closed the four injection-quoting cases. git-clone-clipboard-url now validates the clipboard with =cj/dwim-shell--valid-git-url-p= and passes the URL via =shell-quote-argument= instead of the raw =<<cb>>= substitution. GPG recipient and the 7z archive name go through =shell-quote-argument= instead of hand-written single quotes. The ffmpeg thumbnail timestamp is validated with =cj/dwim-shell--valid-ffmpeg-timestamp-p= (digits/colons/dot only) before it reaches =-ss=. The sequential-rename prefix is validated filename-safe with =cj/dwim-shell--safe-rename-prefix-p=. 7 ERT tests cover the three validators (Normal/Boundary/Error); the two =shell-quote-argument= swaps trust the builtin. The fifth case — video concatenation's echo/tr/sed filelist — is a redesign rather than a quoting fix and is split out below.

***** 2026-05-23 Sat @ 19:58:00 -0500 Rebuilt video-concat filelist in Elisp

=cj/dwim-shell-commands-concatenate-videos= built the ffmpeg concat list with =echo '<<*>>' | tr ' ' '\n' | sed 's/^/file /'=, which split on spaces and broke on quotes. Extracted =cj/dwim-shell--build-concat-filelist=, which renders each path as an escaped =file '...'= line (single quotes escaped as ='\''=), writes it to a temp file in Elisp, and runs =ffmpeg -f concat -i <quoted-listfile>= with a trailing =; rm -f= to clean up after the process exits. =<<*>>= stays only as an inert trailing shell comment so dwim-shell still runs one command over all marked files. 3 ERT tests cover plain paths, spaces, and an embedded quote.

***** 2026-05-23 Sat @ 20:17:00 -0500 Clarified broad/misleading file-operation commands

=remove-empty-directories= ran =find . -type d -empty -delete= from the ambient current directory. Now it prompts for an explicit root (via =read-directory-name=), names that root in the confirmation, and runs =find <quoted-root> ...= built by =cj/dwim-shell--empty-dirs-command= (2 ERT tests cover the command shape + space quoting). =secure-delete= called =shred= without =-u=, overwriting file contents but leaving the file in place despite the name and the "permanently destroy" prompt; added =-u= (=shred -vfzu=) so it actually unlinks. Both use the inert =<<*>>= comment trick for single-execution.

***** 2026-05-24 Sun @ 04:10:20 -0500 Shell-quoted X11 and audio recording command paths

The Wayland =wf-recorder= path already quoted its args, but the X11 =ffmpeg= path and the audio-only =ffmpeg= path interpolated mic device, system device, and output filename raw — breaking on directories with spaces or unusual device names. Wrapped all three in =shell-quote-argument= on both paths. Extracted =cj/recording--build-audio-command= (mirroring =cj/recording--build-video-command=) so the audio command is unit-testable, then quoted there. Tests cover device names and filenames with spaces on both builders. Commit =39795e85=.

***** 2026-05-24 Sun @ 04:10:20 -0500 Scoped wf-recorder stop signal to our own process

Stop ran =pkill -INT wf-recorder=, signalling every wf-recorder on the system including an unrelated screen capture. Added =cj/recording--interrupt-child-wf-recorder=, which scopes the producer-first interrupt to the wf-recorder child of our own recording shell via =pkill -P <shell-pid>=. Producer-first ordering preserved (ffmpeg still sees a clean pipe EOF). The orphan-cleanup at recording start stays a broad by-name kill on purpose — those leftovers come from crashed sessions whose shells are already dead, so there is no live PID to scope to. Tests cover the scoped call, the nil-PID no-op, and that the bare system-wide form is never used. Commit =556f48a2=.

***** 2026-05-24 Sun @ 04:10:20 -0500 Created the selected recording directory, not its parent

The toggles ran =(file-name-directory location)= before =make-directory=, which returns the *parent* for a path without a trailing slash — so the selected directory went uncreated and ffmpeg failed to write into it. Both toggles now route the destination through =cj/recording--normalize-recording-dir= (expand + =file-name-as-directory=) and =make-directory= that, creating the selected directory itself (including names with spaces). Tests cover trailing-slash normalization, idempotence, spaces, and relative-to-absolute expansion. Commit =dc033c75=.

**** TODO [#B] Make AI conversation persistence path-safe and project-aware :refactor:

=ai-conversations.el= has good pure helper seams but is currently untested in
this repo. The path slugging is simple and the save/load/delete commands operate
directly in a single global directory.

Expected outcome:
- Add tests for candidate sorting, topic slug collisions, autosave path setup,
  and delete confirmation behavior.
- Consider whether conversations should remain global or support project-scoped
  subdirectories.
- Confirm autosave never writes partial prompt/response state to an unexpected
  file after loading a different conversation.

**** TODO [#B] Harden calendar sync operational behavior around the parser :refactor:

=calendar-sync.el= has broad parser/recurrence coverage, but the operational
path around it still has startup, persistence, and fetch risks.

Expected outcome:
- Move private calendar URLs out of source and rotate the exposed feed URLs
  before doing further cleanup.
- Avoid immediate network fetches at module load unless explicitly enabled for
  interactive sessions.
- Add a per-calendar in-flight guard so a timer tick cannot launch overlapping
  syncs for the same calendar.
- Use =curl --fail= or equivalent status handling so HTTP error pages are not
  treated as successful ICS downloads.
- Write generated Org files atomically via a temp file and rename.
- Read the local state file with =read-eval= disabled.

**** 2026-05-23 Sat @ 04:18:44 -0500 AI conversation persistence coverage already in place
Premise was stale. =tests/test-ai-conversations.el= (47 cases) already covers slug generation, timestamp parsing, candidate sorting (newest/oldest), latest-file selection, save/load header stripping against a temp dir, autosave path/timer, and delete confirmation — with GPTel stubbed throughout. Acceptance list satisfied; no new file needed.

**** 2026-05-23 Sat @ 03:31:12 -0500 Dirvish helper coverage already in place
The task premise was stale: =dirvish-config.el= now has 14 focused test files (=test-dirvish-config-*.el=, ~100 cases) covering duplicate-naming, resolve-display-path (project/home/absolute/org-link), ediff-pair, html/printable predicates, playlist filtering/sanitizing, wallpaper-program mapping, and the public wrappers. The remaining gaps (playlist name-safety, set-wallpaper nil-file) were filled by the L2668 hardening commit 8fc6432d. No new file needed.

**** 2026-05-23 Sat @ 03:21:12 -0500 Declared dirvish-config runtime deps with plain require
Switched =user-constants= and =system-utils= from =eval-when-compile= to plain =require= in =dirvish-config.el=, matching the three sibling requires below. The module builds =dirvish-quick-access-entries= from =code-dir=/=music-dir=/=pix-dir= at load and binds keys to =cj/xdg-open=/=cj/open-file-with-command=, so the deps are genuine runtime inputs. Added =tests/test-dirvish-config-runtime-requires.el= as a dependency-contract smoke test. Fixed in b63c4f83.

**** 2026-05-23 Sat @ 03:31:12 -0500 Hardened dirvish wallpaper + playlist path helpers
=cj/set-wallpaper= passed =(dired-file-name-at-point)= straight into =expand-file-name=, so no-file-at-point raised a bare wrong-type-argument; added a nil guard that signals a clear user-error. =cj/dired-create-playlist-from-marked= expanded a raw name under =music-dir= with no check; added =cj/--playlist-name-safe-p= to reject any name carrying a directory separator (=../=, absolute, nested) before the path is built. Regression tests went into =test-dirvish-config-wrappers.el= and =test-dirvish-config-playlist.el=. The duplicate/copy-path helpers already guarded nil, so they were left alone. Fixed in 8fc6432d.

**** 2026-05-23 Sat @ 03:38:30 -0500 Coverage already in place for mail + system-commands
The task premise was stale. =mail-config.el= has =test-mail-config-helpers.el= (4), =test-mail-config-transport.el= (7), and =test-mail-config.el= (1) covering executable discovery and transport command assignment. =system-commands.el= has =test-system-commands-keymap.el= (2, keymap shape + candidates) and =test-system-commands-resolve-and-run.el= (13, confirmation routing + command-string construction with shell-command stubbed). Both acceptance lists are satisfied; no new tests needed.

**** 2026-05-24 Sun @ 14:43:13 -0500 Bounded the elfeed YouTube fetch + locked EWW UA scoping

=cj/youtube-to-elfeed-feed-format= called =url-retrieve-synchronously= with no timeout (a hung request blocks Emacs) and only killed the temp URL buffer when an ID was extracted, leaking it on the parse-failure path. Passed =cj/elfeed-url-fetch-timeout= (10s) and moved fetch+parse into an =unwind-protect= that always kills the buffer. The EWW user-agent advice (=eww-config.el=) was already correctly scoped — it injects the UA only from eww-mode buffers, so package.el and other non-EWW url callers pass through untouched — so no code change there, just tests pinning that scoping and the replace-not-duplicate header behavior. Commit =c097b5b4=.

**** 2026-05-16 Sat @ 04:00:00 -0500 Moved Slack which-key registration behind with-eval-after-load

=slack-config.el= calls =which-key-add-keymap-based-replacements= at top level,
while most modules defer which-key registration. If which-key is not loaded or
autoloaded as expected, Slack config can fail during require.

Expected outcome:
- Wrap the registration in =with-eval-after-load 'which-key=.
- Add a module-load smoke test or byte-compile check if easy.

**** 2026-05-16 Sat @ 04:00:00 -0500 Removed httpd-start side effect from markdown-preview

=modules/markdown-config.el:37-51= starts =simple-httpd= inside an
interactive command, then opens a browser at
=http://localhost:8080/imp=.  Starting a network listener as a side
effect of a "preview" command surprises users; once started, the
server keeps running until Emacs exits.  Either gate the start
behind an explicit confirmation, document the listener clearly, or
move the server start into a separate =cj/markdown-preview-server-start=
command so =markdown-preview= just opens the URL once the server is
known to be running.

**** 2026-05-25 Mon @ 18:29:40 -0500 Moved eshell SSH hosts into a defcustom

Replaced the three inline =eshell/alias= SSH-jump lines with a
=cj/eshell-ssh-hosts= defcustom (an alias→remote-path alist defaulting to the
current gocj/gosb/gowolf entries) that a per-machine config can override or set
to nil. The aliases are now built by iterating it via
=cj/--eshell-define-ssh-aliases=; the pure =cj/--eshell-ssh-alias-commands=
helper makes the construction testable without a live eshell. Tests added in
=tests/test-eshell-config-ssh-aliases.el=.

**** 2026-05-16 Sat @ 04:00:00 -0500 Fixed https→http in markdown-preview + extracted server start

=modules/markdown-config.el:45= opens
=https://localhost:8080/imp= via =browse-url-generic=, but the
=simple-httpd= listener bound in =httpd-config.el= serves plain
HTTP on port 8080.  The =https= scheme causes the browser to
attempt a TLS handshake against a plaintext listener -- the request
fails before any preview content reaches the page, so the entire
feature is broken end-to-end.  Change the URL to
=http://localhost:8080/imp= (and consider switching the launch to
=browse-url= so the user's default protocol handler is respected).

**** TODO [#B] Document or vendor strapdown.js CDN dependency in =markdown-preview= :solo:

=cj/markdown-html= (=modules/markdown-config.el:48-51=) embeds a
=<script src="http://ndossougbe.github.io/strapdown/dist/strapdown.js">=
in every rendered page.  The preview silently fails when offline,
when the GitHub Pages host is unreachable, or if the upstream project
disappears.  Document the dependency in the module commentary at
minimum; better, vendor a copy of =strapdown.js= under
=assets/= and serve it from the local =simple-httpd= root.

**** 2026-05-16 Sat @ 04:00:00 -0500 Scoped TERM=xterm-256color to eshell buffers via process-environment

=modules/eshell-config.el:131= calls =(setenv "TERM" "xterm-256color")=
at config time inside the =xterm-color= use-package block.  That
changes =TERM= for the entire Emacs process, so every subsequent
=start-process= / =call-process= inherits =xterm-256color= rather
than the terminal's actual emulator.  Most subprocesses treat it as
truthful and emit ANSI escapes, which surface as raw =\e[31m= bytes
in shells that aren't interpreting them.  Move the setenv into the
eshell entry hook (=eshell-mode-hook= or =eshell-before-prompt-hook=)
so it scopes to eshell processes only.

**** 2026-05-16 Sat @ 04:00:00 -0500 Quoted agent command in cj/--ai-vterm-launch-command via shell-quote-argument

=modules/ai-vterm.el:236-240= builds the tmux launch command by
wrapping =(concat cj/ai-vterm-agent-command "; exec bash")= in
literal single quotes.  The default value carries embedded double
quotes (=claude "Read .ai/protocols.org and follow all
instructions."=) which survives that wrap, but a user-customized
=cj/ai-vterm-agent-command= containing a single quote breaks the
shell parse silently.  Run the inner command through
=shell-quote-argument= (or pass the command as a separate tmux
=new-session= positional argument) so any user-customized agent
command launches safely.

*** 2026-05-15 Fri @ 18:14:26 -0500 Reviewed newly added modules

Fresh end-to-end re-read of the 24 modules listed for this review,
applying the parent's protocol (runtime deps, top-level side effects,
keybindings, timers, external-executable assumptions, secrets,
host-specific paths, user-data writes, and test coverage).

The 24 modules in scope:

- Post-2026-04 additions (11): =telega-config.el=,
  =mu4e-attachments.el=, =vterm-config.el=, =external-open-lib.el=,
  =eshell-config.el=, =cj-window-toggle-lib.el=,
  =cj-window-geometry-lib.el=, =cj-org-text-lib.el=,
  =cj-cache-lib.el=, =nerd-icons-config.el=, =ai-vterm.el=.
- Pre-existing modules outside the original scope (13):
  =text-config.el=, =markdown-config.el=, =latex-config.el=,
  =flycheck-config.el=, =flyspell-and-abbrev.el=, =ledger-config.el=,
  =httpd-config.el=, =chrono-tools.el=, =diff-config.el=,
  =games-config.el=, =mu4e-org-contacts-setup.el=,
  =mu4e-org-contacts-integration.el=, =org-agenda-config-debug.el=.

Confirmed the 5 findings from the 2026-05-15 re-review pass are
filed and visible under their target Harden tracks:
=markdown-config= httpd start (UI/integrations track), =flycheck-config=
LanguageTool path (programming track), =latex-config= Zathura
(programming), =eshell-config= SSH hostnames (integrations), and
=nerd-icons-config= advice-timing / =:demand t= (UI/navigation).

Filed 11 new sub-tasks across the Harden tracks this pass:

- Foundation: dead world-clock block in =chrono-tools.el=, and
  coverage for the TMR sound-selection helpers (with a refactor to
  collapse the prefix-arg duplication).
- Custom editing: de-duplicate the spell-checker availability guard
  in =flyspell-and-abbrev.el=, and add coverage for
  =cj/flyspell-then-abbrev= + helpers.
- Org workflow: declare cross-module free variables in
  =mu4e-org-contacts-integration.el=, and add coverage for the
  completion-at-point / TAB / comma logic there.
- Programming workflow: fix the =cj/prose-helpers-on= toggle bug in
  =flycheck-config.el= (=(if (not (abbrev-mode)) (abbrev-mode))=
  flips the mode twice; needs =bound-and-true-p= + explicit enable).
- Integrations: fix the =https= vs =http= scheme mismatch in
  =markdown-preview=, document/vendor its strapdown.js CDN
  dependency, narrow the global =TERM=xterm-256color= setenv in
  =eshell-config= so it doesn't leak into every subprocess, and
  shell-quote the user-customized agent command in
  =cj/--ai-vterm-launch-command=.

The remaining 13 of the 24 modules had no concrete findings worth
filing -- they are either pure libraries with strong test coverage
(=cj-window-toggle-lib=, =cj-window-geometry-lib=, =cj-org-text-lib=,
=cj-cache-lib=, =external-open-lib=) or thin declarative
configuration (=text-config=, =diff-config=, =ledger-config=,
=games-config=, =mu4e-org-contacts-setup=, =telega-config=,
=httpd-config=, =org-agenda-config-debug=).

** TODO [#C] Unified popup and messenger UX — placement, dismissal, one library :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
Merged 2026-06-20 from the config-wide popup-policy task and the messenger-unification
task — they're the same policy at two scopes (the messenger windows are the first
concrete application of the general popup rules). Two parts:

(A) Config-wide popup policy. All transient popups follow one set of principles.
Placement: when the Emacs frame is wider than tall, the popup rises from the right;
when square or taller, from the bottom — settle the aspect-ratio threshold and the
pop-out percentage. Dismissal: C-c C-c when there's an accept action, C-c C-k when
there's a cancel, otherwise =q= closes the window. Generalizes ai-term adaptive
placement (the aspect-ratio docking) and the messenger window/key rules below into
one config-wide policy. From the roam inbox.

(B) Messenger unification (first application of the policy above).
Spec: [[file:docs/specs/messenger-unification-spec.org][messenger-unification-spec.org]] ([[id:4bfc2011-8ffc-4765-8886-91df12141171][by id]], Draft, 2026-06-11; keybinding-alphabet section + smoke-first parity added 2026-06-16). One library (=cj-messenger-lib.el=) gives every messenger the same shape: chat windows rise from the bottom (the signel rule, generalized), C-c C-c confirms, C-c C-k cancels, C-c C-a attaches — dispatched per backend through a registry + minor mode. Signel already conforms (reference backend); telega and slack join in phases 2-3; ERC later. All eight decisions settled 2026-06-11 (cancel closes an idle window; telega's filter-cancel shadow accepted; slack rooms join the bottom rule). Spec held open — Craig has more ideas to fold in before it's marked Ready.

** TODO [#C] Auto-dim: org headings, links, and tags do not dim in unfocused windows :bug:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
auto-dim-other-buffers-affected-faces (auto-dim-config.el) remaps font-lock and a few org faces to the flat dim face, but not org-level-1..8, org-link, or org-tag, so headings, links (seen in daily-prep.org), and tags like :solo: stay lit when the window loses focus. Decide the dim approach: a flat-dim remap like font-lock (quick) versus dedicated -dim variants surfaced through org-faces / theme-studio (richer, matches the keyword work; Craig flagged org-tags may want the org-faces treatment). Consolidates three roam-inbox captures.
** TODO [#C] "? = curated help menu" convention across modes :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
From the calibredb keybindings work 2026-06-06. The pattern that worked: in a modal/major-mode buffer (calibredb), bind =?= to a curated transient of the frequent workflows, and move the package's own full dispatch to =H=. It fixes the "I can't discover the keys" problem that which-key can't help with (which-key only pops up after a prefix, not for top-level single keys in a mode-map).

Task: survey the modes/modules Craig works in and identify where a =?= -> curated-help-menu (transient) makes sense. Candidates: any major-mode buffer with single-key bindings and no good discovery affordance -- calibredb (done), nov, dirvish, mu4e, ghostel/term, signel, pearl/linear, ELFeed, etc. For each, note whether =?= is free or already a help dispatch, and whether a curated menu (vs the package's own) adds value. Establish it as a convention (and maybe a small helper/macro to define a curated =?= menu consistently).

** TODO [#C] Fix up test runner :feature:refactor:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
*** 2026-05-16 Sat @ 11:15:51 -0500 Ideas
**** Current State
=modules/test-runner.el= is a solid first pass for an Emacs-config-specific ERT
workflow:
- project-scoped focus lists
- run all vs focused mode
- run ERT test at point
- load all test files
- clear ERT tests from other project roots
- keybindings under =C-; t=

The universal test-running direction is currently split across modules:
- =test-runner.el= owns ERT focus/state/UI.
- =dev-fkeys.el= owns F6 language detection and command generation for Elisp,
  Python, Go, and partial TypeScript.

That split is the biggest architectural pressure point.  The test runner should
eventually own runner discovery, scopes, command construction, result handling,
and UI.  F6 should become a thin entry point into the runner.

**** Critical Design Issues
***** Too ERT-specific at the core
The current state model is named generically, but most operations assume:
- test files live in =test/= or =tests/=
- files match =test-*.el=
- tests are ERT forms
- individual tests can be selected by ERT selector regex
- loading tests into the current Emacs process is acceptable

This makes the module hard to extend cleanly to pytest, Jest, Vitest, Go, Rust,
or shell test runners.  The common abstraction should be "test run request" and
"test runner adapter", not "ERT file list".

***** In-process ERT causes state contamination
=cj/test-load-all= and focused runs load test files into the current Emacs
session.  This is fast and ergonomic, but it can leak:
- global variables
- advice
- loaded features
- overridden functions
- ERT test definitions
- load-path mutations

The runner should support two ERT execution modes:
- =interactive= / in-process for fast local TDD
- =isolated= / batch Emacs for reliable verification

The isolated path should be preferred for "before commit", CI parity, and
agent-driven verification.

***** Test discovery is regex-based and fragile
=cj/test--extract-test-names= scans files with a regex for =ert-deftest=.
That misses or mishandles:
- macro-generated tests
- commented forms in unusual shapes
- multiline or reader-conditional forms
- non-ERT Elisp tests such as Buttercup
- stale ERT tests already loaded in the session

Better approach:
- for ERT in isolated mode, let ERT discover tests after loading files
- for source navigation, use syntax-aware forms where possible
- store discovered tests as structured records with file, line, name, framework,
  tags, and runner

***** Path containment has at least one suspicious edge
=cj/test--do-focus-add-file= checks:

#+begin_src elisp
(string-prefix-p (file-truename testdir) (file-truename filepath))
#+end_src

That should use =cj/test--file-in-directory-p= or ensure the directory has a
trailing slash.  Otherwise sibling paths with a shared prefix are a recurring
class of bug.

***** Runner commands are shell strings too early
=cj/--f6-test-runner-cmd-for= returns shell command strings.  That makes it
harder to:
- inspect command parts
- safely quote arguments
- offer command editing
- run via =make-process= / =compilation-start= without shell ambiguity
- attach metadata
- rerun exact invocations
- convert commands into UI labels

Prefer a structured command object:

#+begin_src elisp
(:program "pytest"
 :args ("tests/test_foo.py" "-q")
 :default-directory "/project/"
 :env (("PYTHONPATH" . "..."))
 :runner pytest
 :scope file)
#+end_src

Render to a shell string only at the final compilation boundary.

***** F6 and =C-; t= workflows duplicate the same domain
F6 already handles "all tests" and "current file's tests" for multiple
languages.  =C-; t= handles ERT-only focus and run state.  These should converge
on one runner service:
- F6: quick entry point
- =C-; t=: full runner menu
- both call the same scope/adapter engine

***** Test directory discovery is too narrow
Current discovery prefers =test/= then =tests/=, with a global fallback.  Real
projects often need:
- Python: =tests/=, package-local =test_*.py=, =pytest.ini=, =pyproject.toml=
- JS/TS: =package.json= scripts, =vitest.config.*=, =jest.config.*=,
  =*.test.ts=, =*.spec.ts=
- Go: package directories, =go.mod=
- Rust: =Cargo.toml=, integration tests under =tests/=
- Elisp packages: =Makefile=, =Eask=, =ert-runner=, Buttercup, =tests/=

Discovery should be adapter-specific and project-config-aware.

***** No structured result model
=cj/test-last-results= exists but is not meaningfully populated.  A powerful
runner needs a normalized result model:
- run id
- started/finished timestamps
- status: passed/failed/errored/cancelled/skipped/xfail/xpass
- command
- runner adapter
- scope
- exit code
- duration
- failed test records
- file/line locations
- raw output buffer
- coverage artifact paths

This enables last-failed, failures-first, summaries, dashboards, and AI-assisted
failure explanation.

***** No failure parser / navigation layer
Compilation buffers are useful, but the runner should parse common failure
formats and provide:
- next/previous failure
- jump to source line
- failure summary buffer
- copy failure context
- rerun failed test at point
- annotate failing tests in source buffers

Adapters can provide regexes/parsers for ERT, pytest, Jest/Vitest, Go, Rust,
and shell.

***** Missing watch/rerun modes
Modern test runners optimize the feedback loop:
- pytest supports selecting tests, markers, last-failed, failures-first,
  stepwise, fixtures, xfail/skip, plugins, and cache state.
- Jest/Vitest support watch workflows, changed-file selection, coverage,
  snapshots, and rich interactive filtering.  Vitest also defaults to watch in
  development and run mode in CI.
- Go and Rust runners commonly support package-level runs, regex selection,
  race/coverage flags, and cached test behavior.

The Emacs runner should expose the subset that maps well to editor workflows:
- current test
- current file
- related test file
- focused set
- last failed
- failed first
- changed since git base
- watch current scope
- full project
- coverage for current scope

**** Proposed Architecture
***** Core Types
Use plain plists initially; promote to =cl-defstruct= only if helpful.

#+begin_src elisp
;; Test runner adapter
(:id pytest
 :name "pytest"
 :languages (python)
 :detect cj/test-pytest-detect
 :discover cj/test-pytest-discover
 :build-command cj/test-pytest-build-command
 :parse-results cj/test-pytest-parse-results
 :capabilities (:current-test :file :project :last-failed :coverage :watch))

;; Test run request
(:project-root "/repo/"
 :language python
 :framework pytest
 :scope file
 :file "/repo/tests/test_api.py"
 :test-name "test_create_user"
 :extra-args ("-q")
 :profile default)

;; Test run result
(:run-id "..."
 :status failed
 :exit-code 1
 :duration 2.14
 :failures (...)
 :output-buffer "*test pytest*"
 :artifacts (...))
#+end_src

***** Adapter Registry
Create a registry like:

#+begin_src elisp
(defvar cj/test-runner-adapters nil)
(cj/test-register-adapter 'pytest ...)
(cj/test-register-adapter 'ert ...)
(cj/test-register-adapter 'vitest ...)
#+end_src

Runner selection should consider:
- buffer file extension
- project files
- explicit user override
- available executables
- package manager scripts
- existing Makefile targets

***** Scope Model
Make scopes explicit and shared across languages:
- =test-at-point=
- =current-file=
- =related-file=
- =focused-files=
- =last-failed=
- =changed=
- =package/module=
- =project=
- =coverage=
- =watch=

Each adapter can say which scopes it supports.  Unsupported scopes should produce
clear user-errors with suggestions.

***** Command Builder Pipeline
1. Detect project.
2. Detect language/framework candidates.
3. Resolve user-requested scope.
4. Build structured command object.
5. Optionally let user edit command.
6. Run via =compilation-start= or =make-process=.
7. Parse output/result artifacts.
8. Store normalized result.
9. Update UI/modeline/messages/failure buffer.

***** Keep Makefile Support But Do Not Require It
For this Emacs config, =make test-file= and =make test-name= are useful and
should remain the default Elisp isolated path.  But adapter detection should
support:
- direct =emacs --batch= ERT invocation
- =make test=
- =make test-file=
- =make test-name=
- Eask
- Buttercup

**** Elisp-Specific Improvements
***** Add isolated ERT runs
Support batch commands for:
- all project tests
- one test file
- one test name
- focused files
- last failed, once result parsing exists

Use the same Makefile targets in this repo, but design the adapter so other
Elisp projects can run without this Makefile.

***** Support Buttercup/Eask Later
Buttercup uses BDD-style =describe= / =it= suites and is common in Elisp
package testing.  Eask is often used to run package tests.  Add adapter slots
for these instead of hard-coding ERT forever.

***** Avoid unnecessary global ERT deletion
=cj/ert-clear-tests= is a pragmatic fix for project contamination, but the
stronger long-term answer is isolated runs plus project-scoped discovery.  Keep
the cleanup command, but do not make correctness depend on deleting global ERT
state.

**** Python / pytest Ideas
- Detect pytest by =pyproject.toml=, =pytest.ini=, =tox.ini=, =setup.cfg=, or
  presence of =tests/=.
- Build commands for:
  - project: =pytest=
  - file: =pytest path/to/test_file.py=
  - test at point: =pytest path/to/test_file.py::test_name=
  - class method: =pytest path::TestClass::test_method=
  - marker: =pytest -m marker=
  - last failed: =pytest --lf=
  - failed first: =pytest --ff=
  - stop after first: =pytest -x=
  - coverage: =pytest --cov=...=
- Parse output for failing node ids and =file:line= references.
- Read pytest cache for last-failed where useful.
- Offer marker completion by parsing =pytest --markers= or config files.
- Surface xfail/skip separately from hard failures.

**** TypeScript / JavaScript Ideas
***** Detection
Detect runner by project files and scripts:
- =vitest.config.ts/js/mts/mjs=
- =jest.config.ts/js/mjs/cjs=
- =package.json= scripts: =test=, =test:watch=, =vitest=, =jest=
- lockfile/package manager: =pnpm-lock.yaml=, =yarn.lock=, =package-lock.json=,
  =bun.lockb=

Prefer project scripts over raw =npx= when present:
- =pnpm test -- path=
- =npm test -- path=
- =yarn test path=
- =bun test path=

***** Scopes
- current file: =vitest run path= or =jest path=
- test at point: use nearest =it= / =test= / =describe= string and pass =-t=
- watch current file
- changed tests where runner supports it
- coverage current file/project
- update snapshots

***** Result Parsing
Parse:
- failing test names
- file paths and line numbers
- snapshot failures
- coverage summary

Treat snapshot updates as an explicit command, not an automatic side effect.

**** Go Ideas
- Detect =go.mod=.
- Current file/source: run package =go test ./pkg=.
- Test at point: nearest =func TestXxx= and run =go test ./pkg -run '^TestXxx$'=.
- Bench at point: nearest =BenchmarkXxx= and run =go test -bench '^BenchmarkXxx$'=.
- Add toggles for =-race=, =-cover=, =-count=1=, =-v=.
- Parse =file.go:line:= output and package failure summaries.

**** Rust Ideas
- Detect =Cargo.toml=.
- Use =cargo test= by default, optionally =cargo nextest run= when available.
- Current test at point: nearest =#[test]= function.
- Current file/module where possible.
- Integration test file: =cargo test --test name=.
- Support =-- --nocapture= toggle.
- Parse compiler/test failures and =file:line= links.

**** Shell / Generic Ideas
- Adapter for Makefile targets:
  - detect =make test=, =make check=, =make coverage=
  - expose project-level commands even when language-specific detection fails
- Adapter for arbitrary project command configured in dir-locals or a project
  config plist.
- Let users register custom command templates per project:

#+begin_src elisp
((:name "unit"
  :command ("npm" "run" "test:unit" "--" "{file}"))
 (:name "integration"
  :command ("pytest" "tests/integration" "-q")))
#+end_src

**** UI Ideas
***** Transient Menu
Replace or complement the raw keymap with a =transient= menu:
- scope: current test/file/focused/last failed/project
- runner: auto/ert/pytest/vitest/jest/go/cargo/make
- toggles: watch, coverage, debug, fail-fast, verbose, update snapshots
- actions: run, rerun, edit command, show failures, open report

***** Result Buffer
Create a normalized =*Test Results*= buffer:
- latest status per project
- command and duration
- pass/fail/skip counts
- failure list with clickable =file:line=
- actions to rerun failed/current/all
- links to coverage artifacts

***** Modeline / Headerline Signal
Show the last run status for the current project:
- green passed
- red failed
- yellow running
- gray no run

Keep it quiet and optional.

***** History
Store recent run requests per project:
- rerun last
- rerun last failed
- choose previous command
- compare duration/status against previous run

**** Configuration Ideas
- =cj/test-runner-default-scope=
- =cj/test-runner-prefer-isolated-elisp=
- =cj/test-runner-project-overrides=
- =cj/test-runner-known-adapters=
- =cj/test-runner-enable-watch=
- =cj/test-runner-result-retention=
- per-project override through =.dir-locals.el=

Example:

#+begin_src elisp
((nil . ((cj/test-runner-project-overrides
          . (:adapter pytest
             :default-args ("-q")
             :coverage-args ("--cov=src"))))))
#+end_src

**** Safety And Robustness
- Use structured commands until the final boundary.
- Quote only at render time.
- Avoid shell when =make-process= / =process-file= is sufficient.
- Keep command preview/editing available for surprising cases.
- Detect missing executables before running.
- Add timeouts/cancel commands for long-running or hung tests.
- Do not silently fall back from a missing runner to a different runner unless
  the fallback is visible in the command preview.
- Avoid mutating global =load-path= permanently.
- Keep remote/TRAMP behavior explicit; do not accidentally run local commands
  for remote projects.

**** Coverage Integration
Tie this into the existing coverage work:
- run coverage for current file/scope
- open latest coverage report
- summarize uncovered lines for current file
- support Elisp SimpleCov/Undercover, pytest-cov, Vitest coverage, Go cover,
  and Rust coverage later
- store coverage artifact paths in the normalized run result

**** AI-Assisted Debugging Ideas
- Summarize failing tests from the parsed failure records and raw output.
- Include command, changed files, failure snippets, and relevant source/test
  locations.
- Redact env vars, tokens, Authorization headers, and secrets before sending to
  =gptel=.
- Add commands:
  - =cj/test-runner-explain-failure=
  - =cj/test-runner-suggest-related-tests=
  - =cj/test-runner-summarize-coverage-gap=

**** Migration Plan
***** Phase 1: Internal cleanup
- Fix the task typo and rename current ERT-specific functions or wrap them under
  an ERT adapter.
- Move F6 language detection/command construction from =dev-fkeys.el= into
  =test-runner.el= or a new =test-runner-core.el=.
- Replace shell-string command builders with structured command plists.
- Fix path containment in =cj/test--do-focus-add-file=.
- Make =cj/test-last-results= real for ERT runs.

***** Phase 2: ERT adapter
- Implement adapter registry.
- Add ERT adapter with in-process and isolated modes.
- Preserve all current keybindings by routing them through the adapter.
- Add failure/result normalization for ERT.
- Add "rerun last" and "rerun failed" for ERT.

***** Phase 3: Python and JS/TS adapters
- Add pytest adapter.
- Add Vitest/Jest adapter with package-manager/script detection.
- Support current file and test-at-point for both.
- Add parser/navigation for common failures.

***** Phase 4: UI and watch modes
- Add transient menu.
- Add result buffer.
- Add cancellation and rerun history.
- Add watch commands where supported.

***** Phase 5: Coverage and AI
- Connect coverage commands to adapter capabilities.
- Add failure summarization with redaction.
- Add coverage-gap summarization.

**** Acceptance Criteria For First Fix-Up Pass
- Existing ERT workflow still works.
- F6 and =C-; t= use the same underlying runner API.
- Current-file test command generation is covered for Elisp, Python, Go,
  TypeScript, and JavaScript.
- At least one isolated ERT command path exists.
- Path containment checks are robust against sibling-prefix paths and symlinks.
- Runner requests and results are represented as data, not only messages.
- Missing runner/tool errors are clear and actionable.
- Tests cover adapter detection, command building, scope resolution, result
  storage, and key interactive paths.

** TODO [#C] Keymap consolidation — resolve decisions, run Phase 1-2 :feature:refactor:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
Spec: [[id:540bf06b-16b8-46c6-b459-c40d1b9c795d][keybinding-console-safety-spec-doing.org]]. Phase 0 (revert 4a1ecf64) is done and pushed. Decisions D1-D5 are open TODOs in the spec; D2/D4/D5 gate the primary work (Phase 1 prune via Appendix D, Phase 2 consolidate + retire the translation block), while D1/D3 (the console-safe prefix) gate only the optional Phase 3 and can stay open indefinitely. Resolve D2/D4/D5, then run Phase 1-2. Appendix D is the keybinding pruning checklist. Add a =#+TODO: TODO | DONE SUPERSEDED CANCELLED= header line to the spec if adopting those decision keywords (rulesets convention update, 2026-06-12).

** TODO [#C] Ledger-config audit + guardrail UX :feature:
Now that =modules/ledger-config.el= is wired (6ec857ae), audit it thoroughly — correctness first, then especially the data-entry UX. Goal (Craig): a workflow with enough guardrails that it's hard to make a costly mistake in a financial file. Audit surface: clean-on-save behavior (does =ledger-mode-clean-buffer= ever reorder/rewrite in a surprising way; is the demoted-error swallow hiding real problems), flycheck-ledger coverage (unbalanced transactions, bad account names) and whether it surfaces clearly, reconcile safety, the report set, company-ledger account/payee completion as a typo guard, and any add-transaction entry flow. Identify gaps, then design the guardrails (validation on save, completion to prevent account-name drift, a confirm before destructive reconcile, etc.). The correctness/gap audit can run solo; the UX guardrail choices need Craig's preferences, so not tagged :solo:. Priority [#C] is a placeholder — bump if ledger becomes active daily use.

** TODO [#C] ai-term multi-LLM support — Claude / Codex / ollama :feature:
Allow creating an ai-term that launches any of Claude, Codex, or a local LLM via ollama, switchable at session start. From rulesets/Craig via the roam inbox. Spec note: =inbox/PROCESSED-2026-06-23-2123-from-rulesets-ai-term-multi-llm-support-from-craig.org=.
** TODO [#C] ai-term: multi-backend (Claude / Codex / local ollama) :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-22
:END:
Allow creating an ai-term backed by any of Claude, Codex, or a local LLM via ollama, with the backend chosen seamlessly at the start of the session. ai-term currently assumes Claude; generalize the launch path so the agent backend is a selectable parameter and switching between them at session start is frictionless. Routed here from the rulesets roam-inbox item "multiple agent source improvements" (its bullet 3 asked to send emacs this note); the item's other bullets — naming the agent so non-Claude agents aren't called "Claude", and tightening workflow wording for Codex's more literal reading — stay with rulesets.

** TODO [#C] Migrate tests off mocking primitives (native-comp robustness) :test:refactor:solo:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Long-term test-quality work surfaced by re-enabling native-comp (2026-06-20). When a test redefines a C primitive or a native-compiled function (=cl-letf=/=fset=/=advice-add=), native-comp routes native callers through a trampoline, which interacts badly with mocks in three ways: trampoline-build failure under =--batch=, silent mock-bypass (native callers ignore the redefinition), and arity mismatch (the trampoline calls the mock with the primitive's max arity).

Done 2026-06-21 (the immediate fix): swept every arity-narrow subr mock to =(lambda (&rest _) ...)= (188 sites) and added =tests/test-meta-subr-mock-arity.el=, which fails =make test= on any arity-narrow subr mock. That kills the arity mode (the only one we've hit) and enforces it going forward.

This task is the durable fix the ecosystem and =elisp-testing.md= point to: restructure tests so they don't redefine primitives at all — inject dependencies, drive real state (temp-file fixtures, real buffers), or test pure helpers. That closes the two latent modes (build-failure, silent-bypass) the variadic sweep leaves open. Big, incremental, low-urgency.

Full mechanism, the three failure modes, the research (Emacs bug#51140, bug#61880, buttercup #230, Debian #1021842, the emacs-29 redefine-primitive warning, the manual on =native-comp-enable-subr-trampolines=), and the decision: [[file:docs/native-comp-subr-mocking.org][docs/native-comp-subr-mocking.org]].

** TODO [#C] buffer-differs save prompt: 4-way yes/no/diff/cancel :feature:next:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
The "buffer differs from file" confirmation currently gives only yes/no. Craig wants a 4-way choice with explicit consequences: yes (be explicit it overwrites), no (be explicit it discards this action and continues), diff (show a graphical difftastic diff, then return to this prompt), cancel (stop the action, leave the buffer untouched). Needs the exact prompt identified first (which save/overwrite path raises "buffer differs") and a design for the diff-then-return loop. difftastic + cj/diff-buffer-with-file infrastructure already exist. From the roam inbox 2026-06-16.
** TODO [#C] emacs: tag tasks by module name for sorting :refactor:studio:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Replace topic tagging with single-word module tags: :studio: for everything under scripts/theme-studio/, module-named tags elsewhere, :multi: for cross-area work. Drop bug/enhancement-style tags since work should be chosen on other bases. This changes the current six-tag convention, so update the priority-scheme section to document it, rewrite the task-audit workflow to reconcile tasks against the module scheme, then run the audit. Queue for end of session. From the roam inbox.
** TODO [#C] Build debug-profiling.el module :feature:solo:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:

Reusable profiling infrastructure for targeted slow-command investigation. Consolidates scattered profiler bindings (currently in =modules/config-utilities.el=) and adds two pure-helper-backed entry points: "profile next command" and "time region or sexp." Designed via =/brainstorm= 2026-04-26.

Design: [[id:c713b431-ae14-498d-aba9-b84d52f981b6][docs/specs/debug-profiling-spec.org]]

Implement via =/start-work= against the design — branch =feat/debug-profiling=, commits decomposed along the test-first split-for-testability boundary. Once shipped, use it as the v1 exercise on the queued [#B] org-capture target-building investigation.

** TODO [#C] Evaluate jamescherti essential-emacs-packages list :quick:solo:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Review [[https://www.jamescherti.com/essential-emacs-packages/][James Cherti's essential Emacs packages]] for anything worth installing. Cross-check each candidate against what is already in the config (=modules/= + =init.el=), skip the ones already present, and shortlist the genuinely new ones with a one-line rationale. Future-installation research, not a commitment to install.

** TODO [#C] Extend F2 "preview" convention across modes :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:

F2 is the universal preview key. Currently bound only in markdown-mode (markdown-preview, in =modules/markdown-config.el=). Org-reveal lives on =C-; o R= via =cj/org-map=, not F2. Extend F2 to other modes where a "preview" action is natural:

- Hugo blog (hugo-config.el) — preview the post in browser
- HTML / web-mode — open in browser
- Reveal presentations - preview in browser
- Any other mode with a natural "preview this" action

Keep the binding mode-local so F2 stays available as a global candidate where no preview makes sense.

** TODO [#C] Gold text in auto-dimmed buffers :bug:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Some auto-dimmed document buffers render text in gold; source unknown. Likely a face-remapping or overlay interaction with the theme. Blocked on the face/font diagnostic tool above for diagnosis. From the roam inbox.
** TODO [#C] Google Contacts ↔ org-contacts sync investigation :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
From the 2026-06-11 brainstorm. Goal: keep [[file:~/sync/org/contacts.org][contacts.org]] (real org-contacts: PROPERTIES drawers, mu4e completion, org-roam links) in sync with Google Contacts. Google side is solid — official People API (OAuth2, incremental syncToken) or CardDAV; no ToS risk. The hard parts are local: (1) identity — entries have no UID, so two-way needs a GOOGLE_ID property per entry plus a one-time fuzzy reconciliation of the two populated datasets (name/email/phone matching); (2) field mapping — space-separated multi-email in one property, free-text body notes, inconsistent phone formats (normalization decision); (3) conflict policy. First decision gates the rest: one-way Google→org read model (simple) vs true two-way. Candidate architectures: vdirsyncer (proven two-way engine w/ Google support; build only the vCard↔org translation, evaluate org-vcard fidelity) vs a direct People API script with sync state in org properties. Output: recommendation doc in docs/design/ naming direction + the normalization/conflict decisions for Craig. Not :solo: — the one-way-vs-two-way call and normalization policy are Craig's.

** TODO [#C] Google Voice in Emacs — SMS + dialer investigation :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
From the 2026-06-11 messenger-unification brainstorm. Google Voice has no official API; the viable routes ride the Matrix bridge ecosystem's reverse engineering (mautrix-gvoice). Research pass to establish the 2026 state of play: (1) is mautrix-gvoice healthy and what does its auth flow look like now; (2) any better-maintained alternative (CLI/daemon) for the signel-pattern architecture (external daemon + JSON-RPC + thin Emacs chat client); (3) does call initiation (ring-linked-phone-then-connect, Emacs as dialer) survive in the current protocol — two-way audio in Emacs is out of scope (WebRTC); (4) ToS/account-flag risk assessment for Craig's account. Output: a recommendation doc in docs/design/ naming the architecture (signel-pattern daemon vs Matrix bridge + ement.el) or a no-go with reasons. If go, GV becomes a registered backend under the messenger-unification convention (see the [#B] task below).

** TODO [#C] Org-noter custom workflow — fix and finish :feature:bug:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:

Continue debugging and testing the custom org-noter workflow from 2025-11-21 session.
This is partially implemented but has known issues that need fixing before it's usable.

*Last worked on:* 2025-11-21
*Current status:* Implementation complete but has bugs, needs testing

*Known issues to fix:*

1. /Double notes buffer appearing when pressing 'i' to insert note/
   - When user presses 'i' in document to insert a note, two notes buffers appear
   - Expected: single notes buffer appears
   - Need to debug why the insert-note function is creating duplicate buffers

2. /Toggle behavior refinement needed/
   - The toggle between document and notes needs refinement
   - May have edge cases with window management
   - Need to test various scenarios

*Testing needed:*

1. /EPUB files/ - Test with EPUB documents (primary use case)
2. /Reopening existing notes/ - Verify it works when notes file already exists
3. /Starting from notes file/ - Test opening document from an existing notes file
4. /PDF files/ - Verify compatibility with PDF workflow
5. /Edge cases:/
   - Multiple windows open
   - Splitting behavior
   - Window focus after operations

*Implementation files:*
- =modules/org-noter-config.el= - Custom workflow implementation
- Contains custom functions for document/notes toggling and insertion

*Context:*
This custom workflow is designed to make org-noter more ergonomic for Craig's reading/annotation
workflow. It simplifies the toggle between document and notes, and streamlines note insertion.
The core functionality is implemented but needs debugging before it's production-ready.

**Next Steps:**
1. Debug the double buffer issue when pressing 'i'
2. Test all scenarios listed above
3. Refine toggle behavior based on testing
4. Document the final keybindings and workflow

** TODO [#C] Pick and wire a debug backend for F5 :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:

#+begin_src emacs-lisp
  Give me an idea of the amount of work and complexity and what allows for a consistent UX across languages. 
#+end_src

*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals
Bind F5 globally to a debug entry point. Backend choice is the hard part:

- dape (Debug Adapter Protocol for Emacs) — modern, multi-language via DAP. Single UX across Python, Go, TS, Rust, etc. Less mature than DAP clients in other editors.
- realgud — wraps multiple debuggers (pdb, gdb, node --inspect, etc.). More mature; UX varies by backend.
- Language-specific stacks — dap-mode (python-mode + dap), delve for go, ts-node --inspect, etc. Best per-language UX; most config work.

F5 itself will be simple (start/resume debug). Likely modifier variants once the backend is picked:
- C-F5 toggle breakpoint at point
- M-F5 eval expression in debug context (or step-over shortcut)

Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip.

Do this after the F-key rework ticket ships so F5 is the only hole left.

** TODO [#C] Review and rebind M-S- keybindings :refactor:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:

Changed from M-uppercase to M-S-lowercase for terminal compatibility.
These may override useful defaults - review and pick better bindings:
- M-S-b calibredb (was overriding backward-word)
- M-S-c time-zones (was overriding capitalize-word)
- M-S-d dwim-shell-menu (was overriding kill-word)
- M-S-e eww (was overriding forward-sentence)
- M-S-f fontaine (was overriding forward-word)
- M-S-h split-below
- M-S-i edit-indirect
- M-S-k show-kill-ring (was overriding kill-sentence)
- M-S-l switch-themes (was overriding downcase-word)
- M-S-m kill-all-buffers
- M-S-o kill-other-window
- M-S-r elfeed
- M-S-s window-swap
- M-S-t toggle-split (was overriding transpose-words)
- M-S-u winner-undo (was overriding upcase-word)
- M-S-v split-right (was overriding scroll-down)
- M-S-w wttrin (was overriding kill-ring-save)
- M-S-y yank-media (was overriding yank-pop)
- M-S-z undo-kill-buffer (was overriding zap-to-char)

** PROJECT [#C] Music Open Work
Parent grouping the open music / EMMS issues; close each child independently.
*** VERIFY [#C] music: extract faces for music config :refactor:quick:next:
Needs from Craig: this is theme-side work, not a config edit — the music-config faces were already stripped (2026-06-14), so "extracting" them means DEFINING them in the theme (theme-studio JSON / build-theme) for playlist name, status, the per-button on/off pair, per-key symbol+text, and other labels. That needs the actual color choices and which theme(s) to add them to. Give me the palette intent (or say "pick sensible defaults in WIP") and I'll add the face definitions.
Pull the music-config faces out to the theme (the config no longer defines faces directly): playlist name, status (paused, etc.), two mode colors per "button" (on vs off), a per-key symbol+text color, and a color for all other labels. Pairs with the 2026-06-14 face-stripping work (music-config faces were removed there and are currently undefined until the theme defines them). From the roam inbox 2026-06-15.
*** TODO [#C] music: show song information in the modeline          :feature:
Show basic song information in the modeline, with streaming-source support too. Write a spec for this one first. From the roam inbox 2026-06-15.
*** TODO [#C] Internet radio now-playing  song                      :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-11
:END:
Show the currently-playing song while streaming an internet radio station. Lives in =modules/music-config.el= (EMMS + MPV backend, M3U radio stations). The track title comes from the stream's ICY metadata — EMMS exposes it via =emms-track-description= / =emms-playing-time= and updates it on the metadata-change hook; MPV reports the ICY title too. Add an option to show the song in the minibuffer (e.g. echo on track change, or an on-demand command). Consider also a mode-line indicator as a second surface.

*** VERIFY [#C] music-config option-combination audit + tests     :test:next:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-06
:END:
Deferred from the batch — this is a sizable test-writing audit (pairwise option combinations + new ERT coverage for music-config), better as its own focused /add-tests or /pairwise-tests session than crammed into a bug-fix sweep. No blocker; say the word and I'll run /pairwise-tests over the option space.

Two-part task surfaced 2026-05-28 during the Signel verify walk — generalized from the "are there combinations of options that we'd want to disallow together" question.

Part 1 — enumerate the configurable option surface of =modules/music-config.el=: every =defcustom=, every behavior toggle, every backend-selection variable, every cross-cutting flag (auto-play, repeat, shuffle, follow-cursor, side-window-height-fraction, etc.). Audit each option for valid value ranges. Capture the matrix in =docs/design/music-config-options.org= (or inline in the test file's header — judgment call when the matrix lands).

Part 2 — combinatorial test coverage. Use the =/pairwise-tests= skill: identify parameters, value partitions, and inter-parameter constraints, build a PICT model, generate the minimal test matrix that hits every 2-way combination. For each problematic combination the matrix surfaces, decide: (a) validate at config-load time with a =user-error= that names the conflict, (b) runtime guard in the affected command, or (c) doc-only warning in the option's docstring. Disallow only the genuinely-broken pairs; doc-warn the merely-confusing ones.

The recent F10 side-window-height-fraction work and the EMMS-free refactor candidate ("Implement EMMS-free music-config architecture" above) are both natural near-term touchpoints — best to land this audit before the EMMS swap so the new architecture inherits a clean option spec.

*** TODO [#C] Implement EMMS-free music-config architecture :refactor:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-01
:END:
**** 2026-05-15 Fri @ 19:17:01 -0500 Specification
Implement the design in [[id:423bc355-18d3-4e39-9e7a-f768b865d95b][Design: music-config Without EMMS]].

The implementation should make =music-config.el= load without EMMS, introduce
package-owned playlist and track state, add a =cj/music-playlist-mode= view,
and route playback through a small backend protocol with an initial =mpv=
backend.  Preserve the current F10 and =C-; m= user workflows where practical,
and keep M3U load/save/edit/reload plus radio station creation working.

Complexity estimate: high.  This is a module rewrite with a new internal data
model, package-owned playlist mode, backend protocol, mpv process management,
and migration of existing EMMS-backed commands/tests.

Time estimate: 2-4 focused days for an EMMS-free v1 with play/stop/next/previous,
M3U persistence, playlist UI, and focused tests.  Add another 1-2 days if v1
must include full mpv IPC support for pause, seek, and volume parity.

Acceptance checks:
- =music-config.el= can be required in batch with no EMMS package installed.
- Existing focused music tests pass without EMMS preload or EMMS stubs except
  where a compatibility adapter is explicitly under test.
- New tests cover playlist state, backend command dispatch, M3U persistence,
  and the EMMS-free load smoke path.

**** TODO [#B] Pure helpers + state structs extraction :refactor:
Lift EMMS-free pure code into standalone form: file validation, recursive
collection, M3U parse/write, safe filenames, radio-station content, and
URL/file track typing.  Introduce =cj/music-track= and =cj/music-playlist=
cl-structs plus state-mutation helpers (=cj/music-playlist-*= predicates and
setters).  Files: =modules/music-config.el=, possibly a new
=modules/music-state.el= split.  Existing pure-helper tests should pass
unchanged.

Acceptance: structs defined, helpers callable in batch without EMMS loaded.

Depends on: none (start here).

**** TODO [#B] Backend protocol + fake test backend :refactor:test:
Define the backend plist contract (=:available-p :play :pause :resume :stop
:seek :volume :status :metadata=) and =cj/music-current-backend=.  Add
=cj/music-state-change-functions= abnormal hook with the v1 event set
(=started=, =paused=, =resumed=, =stopped=, =finished=, =error=,
=playlist-changed=, =mode-changed=).  Create =tests/testutil-music-backend.el=
exposing =cj/test-music-fake-backend= with an event ledger.

Acceptance: fake backend installable in tests; ordered-event assertions work
against a no-op playback flow.

Depends on: pure helpers + state structs.

**** TODO [#B] Read-side state API + characterization tests :test:refactor:
Implement =cj/music-playing-p=, =cj/music-paused-p=, =cj/music-current-track=,
=cj/music-playlist-state=, =cj/music-track-description=.  Before rewriting
command bodies, add characterization tests against current behavior for
=cj/music-next=, =cj/music-previous=, =cj/music-toggle-consume=,
=cj/music-playlist-toggle=, =cj/music-playlist-load=, =cj/music-playlist-clear=
so the migration has a safety net.

Acceptance: read-side helpers covered; characterization tests green against
the current EMMS-backed implementation.

Depends on: backend protocol + fake test backend.

**** TODO [#B] Playlist major mode + render-from-state :feature:
Add =cj/music-playlist-mode= rendering the buffer as a view over
=cj/music-current-playlist=.  Selected-track overlay + face, header reads
package state, full keymap from design Section "Playlist Buffer" (RET/p, SPC,
s, >/<, f/b, +/=/-, a, A, c/C, L/S/E/g, r/t/z/x, Z, i, o, q, S-up/down).
Preserve the active-window background highlight.

Acceptance: opening the playlist renders package state; reorder/shuffle/clear
go through state mutations and re-render; tests cover header + overlay
positioning.

Depends on: read-side state API.

**** TODO [#B] mpv backend implementation :feature:
Implement =cj/music-mpv-*= backend functions.  Phase the work per migration
plan §5: (a) process spawn, UID/PID-stamped socket under
=temporary-file-directory=, stale-socket sweep, IPC connect via
=make-network-process :family 'local=, state-hook plumbing.  (b) play/stop/
next/previous + finished-track auto-advance with deliberate-stop tracking.
(c) pause/resume, seek, volume over JSON IPC.  (d) metadata read on track
start.  Add =cj/music-doctor= reporting platform capabilities; ship Windows
degraded mode (play/stop/next/previous only via stdin/=call-process=).

Acceptance: integration tests tagged =:slow= and skipped when =mpv= not on
PATH; on Linux/macOS pause/seek/volume parity works; clean socket lifecycle
across Emacs restart and exit.

Depends on: backend protocol + fake test backend.

**** TODO [#B] Command + Dired/Dirvish rewire :refactor:
Migrate user-facing commands (=cj/music-play=, =cj/music-pause=,
=cj/music-stop=, =cj/music-next=, =cj/music-previous=, seek/volume,
random/repeat/consume/shuffle toggles) to operate on package state and call
=cj/music-current-backend=.  Update Dired/Dirvish =+= add routing,
M3U load/save/edit/reload, radio-station creation, F10 toggle, and =C-; m=
keymap entries to drop EMMS symbols.  Migrate command-flow tests to the fake
backend.

Acceptance: full keymap functional end-to-end against the fake backend;
characterization tests still green; Dirvish =+= add path covered.

Depends on: playlist major mode + mpv backend.

**** TODO [#B] EMMS removal + parity walk :test:
Remove =cj/emms--setup=, the on-demand EMMS loader, and the =use-package emms=
block.  Add the EMMS-free batch-load smoke test (=music-config.el= requires
clean without EMMS installed).  Run the 22-step parity walk from design
§"Parity Walk" against the new implementation; record measurements against
the performance budget (1000-track load <500ms, reorder <50ms, IPC dispatch
<100ms, header refresh <16ms) and note any deviations.

Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity
walk recorded as a completion log entry under the parent task.

Depends on: command + Dired/Dirvish rewire.

** PROJECT [#C] Calibre Open Work
:PROPERTIES:
:LAST_REVIEWED: 2026-06-06
:END:
Parent grouping the open Calibre / ebook-workflow issues; close each child independently. The EPUB reading-width tasks were already resolved (2026-05-12/14).

*** 2026-06-12 Fri @ 07:34:05 -0500 Calibre bookmark naming ships "Author, Title" from the filename
When I hit m in calibre, I'm making my place in the book with a bookmark.
While sometimes, the books look fine: "The A.B.C. Murders - Agatha Christie.epub"
Sometimes they look not so good: Engines of Logic_ Mathematicians and the O - Martin Davis.pdf or Software Architecture_ The Hard Parts _ Mo - Neal Ford.pdf

What I would like to do is to have the bookmarks be saved in the following format:

Author, Title [no extension]. Underscores should be stripped.

Root cause: in a nov buffer =m= is =bookmark-set= (rebound at calibredb-epub-config.el:311); nov's =nov-bookmark-make-record= names the record =(buffer-name)= -- the EPUB filename.

Implemented 2026-06-06. Source decision: parse the *filename*, not the embedded EPUB metadata -- under Calibre's "<Title> - <Author>.epub" naming the filename is more complete (the embedded metadata had truncated titles, author-sort "Last, First" forms, and lost punctuation; see the separate metadata-cleanup task). A =:filter-return= advice on =nov-bookmark-make-record= rebuilds the name from the record's filename: split on the last " - " into title/author, restore the colon Calibre sanitized to "_ " (-> ": "), reorder to "Author, Title". Pure helpers =cj/--nov-clean-title= + =cj/--nov-bookmark-name-from-file= in =modules/calibredb-epub-config.el=; 10 ERT tests in =tests/test-calibredb-epub-config--bookmark-name.el=. Live in the daemon.

Existing bookmarks: the 3 nov bookmarks in =~/sync/org/emacs_bookmarks= were renamed by hand (one-pass, in the daemon + saved; backup at =emacs_bookmarks.bak-2026-06-06=): "Edward Kanterian, Frege: A Guide for the Perplexed", "Agatha Christie, The A.B.C. Murders", "Edward Abbey, The Fool's Progress: An Honest Novel".

Manual verify filed under the Manual testing and validation parent.

*** 2026-06-12 Fri @ 07:34:05 -0500 Curated Calibre keybinding menu + docked description shipped
Relocated from the global capture inbox 2026-06-06. Want a discoverable set of keybindings (visible in which-key) for the most frequent calibredb workflows:
- Switch to a library (e.g. Literature), sort by last name, scroll the list.
- Scope/filter the list in place, keeping the current library scope:
  - by format (e.g. epubs only)
  - by author last name (exact == or ^begins-with some text)
  - sort by title, publication date, or group by format
- One key pops up the selected book's description in a bottom-30% buffer, dismissed with q (same display pattern as the signel chat dock).
- RET opens the book in the appropriate viewer.
Survey finding 2026-06-06: calibredb already binds almost all of this in calibredb-search-mode-map (S/L library, g filter [f format, a author, t tag, d date], o sort [t title, a author, p pubdate, f format], RET open) and even ships transient menus (? = calibredb-dispatch, g, o). The real problem was discoverability -- they are top-level single keys (which-key never pops up) and Craig didn't know ? opened a menu. calibredb-quick-look is macOS-only; the detail view (v -> *calibredb-entry*, q quits) is the description but opens full-window.

Implemented 2026-06-06 in =modules/calibredb-epub-config.el=:
- A curated transient =cj/calibredb-menu= (library switch; filter format/author/reset; sort author/title/pubdate/format; open; describe; H = full calibredb-dispatch) bound to =?= in calibredb-search-mode-map. calibredb's own full dispatch moved to =H=. Defined in the use-package =:config= (needs the elpa transient, which batch doesn't load) -- the "? brings up a curated help menu" convention.
- Bottom-30% description dock: =calibredb-show-entry-switch= -> =pop-to-buffer= + a =display-buffer-alist= rule for =*calibredb-entry*= (display-buffer-at-bottom, height 0.3); =cj/calibredb-describe-at-point= shows the entry without switching focus so q dismisses it. Same pattern as the signel chat dock.
1 ERT test (the describe command; the transient/bindings/dock need the elpa transient + live calibredb, verified in the daemon). Author "begins-with" is covered well enough by g a's completing-read over "Last, First"; a true regex filter was not built. Manual verify filed under the Manual testing and validation parent.

*** TODO Embed Calibre DB metadata into the EPUB files
Surfaced 2026-06-06 while building the bookmark naming: the metadata embedded in the EPUB files' OPF is worse than Calibre's database metadata. nov reads the embedded OPF and got truncated titles ("Frege" vs the filename's "Frege: A Guide for the Perplexed"), author-sort "Last, First" forms ("Christie, Agatha"), and lost punctuation ("A.B.C." -> "A B C"). The filenames (from Calibre's curated DB) are the good copy. Fix on the Calibre side: select all (or by library), run "Edit metadata -> Embed metadata into book files" so the DB metadata is written into each EPUB's OPF. Consider auditing author vs author_sort first. After embedding, the in-file metadata matches the library and any tool reading the files (nov, other readers, re-imports) gets the good data. Not an Emacs task; Calibre-side bulk maintenance.

** PROJECT [#C] 2026-06 full config audit — findings backlog :refactor:
Module-by-module review of all 121 modules + init/early-init, holistic passes (startup/perf, stability, UX consistency, package strategy), and spin-offs into pearl, chime, emacs-wttrin. Method: parallel read-only review agents per module group; key claims spot-verified (incl. against the live daemon) before filing. Run 2026-06-11/12, COMPLETE. Tally: ~165 module findings + ~40 holistic + 30 spin-off ≈ 235 total; 40 high-impact bugs filed as standalone tasks above this parent; the rest live in the group children below. Spin-off findings delivered as inbox handoffs to pearl, chime, and emacs-wttrin (2026-06-12-0057). Start with the synthesis child below for the recommended attack order.

*** Synthesis: the overall picture and attack order
Six cross-cutting themes, then the order I'd work them.

Themes:
1. Performance has one systemic lever, not many small ones: native-comp is accidentally OFF config-wide and GC sits at the stock 800KB ([#A] task). Daemon init itself is healthy (1.11s measured). Fix the lever before any micro-deferral work, and before burning time on the org-capture-perf debug.
2. A "dangerous defaults" safety cluster: yes-or-no-p fset (single-keystroke shutdown/file-destruction), the silently-failing Wayland lock screen, erc-yank's public gists, mu4e's broken trash/refile on the primary account. All four are [#A]/[#B] standalones; do these first — they're where the config can actually hurt you.
3. Calendar/agenda data correctness: calendar-sync's RFC trio (vanishing final occurrences, resurrected cancelled meetings, collapsed multi-day events) + agenda sources missing roam Projects. Meetings are missed over this.
4. Recurring mechanical defect classes worth sweeping as one commit each, config-wide: use-package :hook "-hook" suffix trap (org-babel, eshell, latex); eval-when-compile-only requires read at runtime (auth-config, keyboard-macros, erc-config); M-S-<letter> bindings vs uppercase events (4 dead keys + 1 asymmetry); raw C-; entries bypassing cj/register-prefix-map (8 modules); unreachable modules (prog-lsp, ledger-config, show-kill-ring, mu4e-org-contacts-setup); config for package versions long gone (mu4e 1.7 block, dashboard override, org timeline, checkdoc-arguments).
5. The test suite has a blind-spot class: characterization tests asserting BROKEN output (reverse-lines, heavy-box, undo-kill's explicit 0), unit tests hand-building data that hides integration mismatches (F7 coverage paths), and an integration gate that prints green over "Ran 0 tests" (chime). When fixing any standalone bug above, fix its test to assert correct behavior — and consider extending the architecture smoke test to mechanically pin the class-4 sweeps (hooks must be bound after load, no raw C-; binds, no M-S-<letter> specs, no eval-when-compile requires of runtime vars).
6. Consistency wants conventions, not patches: one notification facade (cj/notify — messenger spec addendum already covers the messenger half), one confirmation tier (the fset fix), one prefix-registration mechanism with labels, one buffer-naming shape. The messenger-unification registry mindset generalizes.

Attack order: (a) the three [#A]s + gptel-shadow (it's blocking the filed gptel-magit investigation); (b) the daily-data pair — mail trash/refile + calendar RFC trio; (c) the :quick:solo: standalone sweep — roughly 20 one-to-five-line fixes, a satisfying solo batch; (d) the class-4 mechanical sweeps, one commit per class, each with its smoke-test guard; (e) the consistency conventions, opportunistically as those modules get touched.

*** TODO Findings: foundation/system group
From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks:
- [BUG] =keyboard-compat.el:121= — terminal arrow-key fix runs once on emacs-startup-hook; =input-decode-map= is terminal-local, so =emacsclient -t= frames under the daemon never get it. Register on =tty-setup-hook= (GUI half already uses =server-after-make-frame-hook=).
- [BUG] =config-utilities.el:142= — =cj/recompile-emacs-home=: =(boundp 'native-compile-async)= is always nil (it's a function — needs =fboundp=), so native compilation is never selected; and the helper deletes =<dir>/eln= when the real cache is =eln-cache/= (derive from =native-comp-eln-load-path=). Extend the existing test.
- [BUG] =system-utils.el:94= — success message args swapped: prints "Running notes.txt on mpv...". Trivial; wired into dirvish (O) and calibredb so it shows regularly.
- [REMOVE] =local-repository.el:51= — =localrepo-initialize=, its three defcustoms, and unprefixed =car-member= are dead; early-init owns archive setup with its own divergent path constant. Shrink to =cj/update-localrepo-repository= pointed at early-init's =localrepo-location=.
- [REMOVE] =keybindings.el:146-147= — C-x C-f unset/reset is a no-op (already find-file); comment wrong. Delete or retarget.
- [COVERAGE] =local-repository.el= — only module in the group with no test file.

*** TODO Findings: UI core group
From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks:
- [BUG] =font-config.el:262= — emojify =:defer 1= means :config runs before any daemon GUI frame exists; =env-gui-p= picks ='unicode= permanently, GUI frames never get image emojis. Compute per-frame (=server-after-make-frame-hook=) or test =(daemonp)=.
- [BUG] =font-config.el:283= — =cj/display-available-fonts= errors on second invocation: first call's =special-mode= sets read-only; next call's erase/insert signals. Wrap in =inhibit-read-only=. (Also [COVERAGE]: untested — a call-twice test catches it.)
- [UX] =undead-buffers.el:82= — =cj/kill-other-window= in a single-window frame kills the buffer you're looking at (other-window no-ops; only delete-window is guarded). Add the sibling's =(user-error "No other window")= guard.
- [UX] =undead-buffers.el:48= — C-u C-x k silently marks a buffer undead (then it refuses to die with no explanation later). Undocumented mode-switch inside a core-command remap; document or split into its own command.
- [ENHANCE] =ui-theme.el:87= — theme persistence silently fails on a fresh machine until =persist/= exists; =make-directory= before the writability check.
- [REMOVE] =dashboard-config.el:32-58= — =dashboard-insert-bookmarks= override is dead code: the :demand t require lets upstream dashboard-widgets.el redefine it; behavior survives only because upstream natively honors the settings now. Delete.
- [REMOVE] =font-config.el:199-220= — all-the-icons stack (2 =:demand t= packages + unprompted network font install on fresh machines) likely redundant with nerd-icons everywhere; verify keyboard-compat's reference then drop.
- [REMOVE] =ui-config.el:185= — duplicate =(use-package nerd-icons :defer t)= stanza; nerd-icons-config owns it. Delete stanza + stale Commentary bullet.

*** TODO Findings: buffer/window libs group
From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks:
- [REMOVE] =show-kill-ring.el= — loaded by nothing (init require deliberately removed in b785a19d), so its M-S-k binding is dead; =keyboard-compat.el:177= still installs the M-K → M-S-k translation whose only purpose was this module. Re-add or delete module + stale translation/comment (consult-yank-pop largely supersedes it).
- [UX] =selection-framework.el:38= — =vertico-sort-function= custom is dead config: =vertico-prescient-mode= (line 250) replaces sorting when it activates. Pick one policy (drop the custom, or =vertico-prescient-enable-sorting nil=).
- [BUG] =custom-buffer-file.el:486= — =cj/view-email-in-buffer= leaks MIME handles when no displayable part: =user-error= fires before =mm-destroy-parts=. unwind-protect.
- [ENHANCE] =custom-buffer-file.el:49= — eager =(require 'mm-decode)= at startup only for macro expansion; runtime require already exists at line 481. Make it =eval-when-compile=.
- [UX] =custom-buffer-file.el:221= — =cj/copy-link-to-buffer-file= is a silent no-op in non-file buffers while siblings signal =user-error=. Match them.

*** TODO Findings: editing helpers group
From agents 2026-06-11; spot-verified sample (jump-paren, sortable-time confirmed). Beyond the standalone heavy-box task:
- [BUG] =custom-misc.el:48= — jump-to-matching-paren with point ON a closer lands at the last inner sexp, not the opener (batch-verified). =(forward-char)= before =(backward-sexp)= in the char-after-closer case; the test only covers the after-closer position.
- [BUG] =custom-datetime.el:71= — "sortable" time format is 12-hour ="%I:%M:%S %p %Z"= — "01:00:00 PM" sorts before "09:00:00 AM". Should be ="%H:%M:%S"=.
- [BUG] =custom-comments.el:82= — =cj/comment-reformat= prints "No region was selected" even on success (message outside the if-else), and the fill-column shrink/restore isn't unwind-protected — an error leaves fill-column permanently -3. Use let-binding + =user-error=; also =mark-active= vs the config's usual =use-region-p=.
- [BUG] =custom-line-paragraph.el:52= — join-line-or-region without region inserts a spurious blank line mid-buffer (verified); only insert the newline at eobp.
- [BUG] =custom-line-paragraph.el:77= — duplicate-line-or-region splits a mid-line-ending region via open-line and duplicates an extra empty line when the region ends at bol. Normalize bounds to whole lines.
- [BUG] =custom-ordering.el:158= — reverse-lines and number-lines mishandle the trailing newline ("a\nb\n" → "\nb\na"); the trailing-newline test asserts the broken output. =cj/--arrayify= (line 43) has the correct pattern — apply it; fix the characterization test.
- [BUG] =custom-comments.el:152= — inline-border lines come out 2 chars short for even-length or empty text (parity computed from text length instead of remaining width); stacked dividers misalign.
- [UX] =custom-text-enclose.el:216= — indent-lines =(interactive "p\nP")= couples COUNT and USE-TABS to one prefix arg — multi-column space indent is impossible interactively; docstrings claim "default 4" but "p" defaults to 1 (same in dedent :256).
- [REMOVE] =custom-ordering.el:90= — =cj/arrayify-python= is byte-identical to =cj/arrayify-json= (two bindings, same output). Delete one or differentiate (single quotes for Python).
- [UX] =custom-case.el:66= — title-case contradicts its docstring: "is" is in word-skip despite "linking verbs are major words"; no sentence-restart capitalization after periods; no capitalize-last-word rule. Align list + docstring.

*** TODO Findings: text/prose tools group
From agents 2026-06-11. Beyond the standalone markdown/latex tasks:
- [BUG] =text-config.el:72= — "M-S-i" for edit-indirect-region is unreachable: Meta+Shift+i generates the event M-I, not M-S-i, so the keypress falls back to M-i tab-to-tab-stop. Rebind as "M-I" (the "was M-I" comment thought the rename was a no-op; it wasn't).
- [BUG] =keyboard-macros.el:46= — user-constants required only =eval-when-compile= but =macros-file= is read at runtime; works only because init.el loads user-constants first. Plain require (same trap as auth-config).
- [BUG] =keyboard-macros.el:137= — kill-emacs-hook fires =y-or-n-p= + an interactive name prompt whenever any last-kbd-macro exists — hazardous for daemon/systemd shutdown (no one to answer) and noisy for throwaway macros. Guard =(and last-kbd-macro (not noninteractive))= minimum; consider dropping the prompt (M-F3 already persists named macros).
- [BUG] =lorem-optimum.el:221= — empty Markov chain (missing assets/liber-primus.txt) makes =cj/lipsum-insert= do =(insert nil)= — cryptic wrong-type error far from cause. Signal =user-error= naming the fix; also Commentary advertises "M-x cj/lipsum" but it has no interactive spec.
- [UX] =flyspell-and-abbrev.el:230= — every C-' press re-runs =flyspell-buffer= over the whole buffer while flyspell-mode is off (the documented word-by-word workflow = O(buffer) per keypress in large files). Call =cj/flyspell-on-for-buffer-type= so the mode sticks and the scan runs once.
- [ENHANCE] =text-config.el:121= — accent is wired to the company backend (=accent-company=); the filed Company→Corfu migration task doesn't list it, so C-` breaks silently post-migration. Add to the migration scope or switch to =accent-menu= now.

*** TODO Findings: org core group
From agents 2026-06-11; spot-verified sample (dailies head, babel hook, void bindings confirmed). Beyond the standalone tasks:
- [BUG] =org-babel-config.el:27= — =:hook (org-babel-after-execute-hook . org-redisplay-inline-images)= gets a second "-hook" appended (symbol unbound at expansion, doesn't end in -mode) → registers on nonexistent =org-babel-after-execute-hook-hook=; inline dot-graph images never refresh after C-c C-c. Write =(org-babel-after-execute . ...)= or add-hook in :config.
- [BUG] =org-roam-config.el:67,71= — C-c n p / C-c n w bound (and which-key-labeled) to =cj/org-roam-find-node-project= / =-webclip=, defined nowhere — keypress errors "autoloading failed to define function". Define via =cj/org-roam-find-node= (a project template exists) or drop bindings + labels.
- [BUG] =org-export-config.el:74-81= — ox-texinfo block can never run (=:defer t=, no trigger, excluded from line-47 dolist and =org-export-backends=); commentary still advertises Texinfo. Add to the dolist or delete; also commentary says "subtree default scope" vs actual ='buffer= (line 61).
- [UX] =org-roam-config.el:50-63= — two parallel template dirs drift: :custom templates read =~/.emacs.d/org-roam-templates/= while find-node-topic/recipe read =roam-dir/templates/= — overlapping recipe/topic/v2mom files, edits don't propagate. Pick one canonical dir.
- [REMOVE] =org-agenda-config.el:84= — dead =timeline= entry in org-agenda-prefix-format (removed in org 9.1). Also =org-config.el:47-48= — the TASK note claiming =org-indent-indentation-per-level= "doesn't exist" is wrong (real org-indent defcustom); restore the setq or fix the comment.
- [REMOVE] =org-babel-config.el:161= — =org-html-footnote-separator= is an ox-html setting parked in the babel module with a wrong comment; =org-roam-config.el:76= similarly hides =org-agenda-timegrid-use-ampm= in roam's :config (only takes effect after roam loads). Move both to their owning modules.
- [REMOVE] =org-roam-config.el:363-390= — 28-line commented consult-org-roam block on a TASK comment; its proposed C-c n l / C-c n r now collide with live bindings, so it can't ship as written. Decide + delete (git keeps the draft).
- [COVERAGE] =org-agenda-config.el:423= cj/add-timestamp-to-org-entry (defvar-inside-defun smell), =org-roam-config.el:115,185= node-insert-immediate + finalize-hook — untested.

*** TODO Findings: org apps + calendar-sync group
From agents 2026-06-11/12; spot-verified sample (UNTIL comparisons, EXDATE regex, drill setq confirmed). Beyond the standalone tasks:
- [BUG] =org-reveal-config.el:241= — seven raw =global-set-key= "C-; p ..." calls carry a hidden load-order dependency on keybindings.el (signals "non-prefix key" otherwise); every sibling uses =defvar-keymap= + =cj/register-prefix-map=. Convert.
- [BUG] =org-drill-config.el:131= — =:load-path "~/code/org-drill"= dev checkout breaks drill on machines without it (velox already diverges per the gptel-magit task). Guard with =file-directory-p= fallback to :vc.
- [UX] =org-contacts-config.el:146= — =cj/org-contacts-find= visits the file BEFORE prompting (C-g strands you at point-min) and plain =search-forward= can match body text in another entry. Collect heading positions in org-map-entries, goto after prompt.
- [REMOVE] =calendar-sync.el:1240= — =calendar-sync--fetch-ics= (buffer-string variant) is dead; the sync path uses the temp-file variant exclusively. 30 lines of duplicate curl/sentinel logic that will drift.
- [REMOVE] =org-webclipper.el:216-241= dead commented keymap blocks; =org-contacts-config.el:118-124= commented duplicate capture template flagged "TASK: duplicate?!?". Delete both (git keeps drafts).
- [COVERAGE] =calendar-sync.el:1274= — fetch sentinel branches (curl failure, temp-file cleanup, signal exit) untested; dispatch tests stub above this layer.

*** TODO Findings: mail group
From agents 2026-06-12; spot-verified sample (cmail trash gap, no refile folders, gmail-first contexts confirmed). Beyond the standalone [#A] task:
- [BUG] =mail-config.el:392-407= — C-; e account nav lambdas call =mu4e-search=, not autoloaded — void-function before first mu4e launch. Add to :commands or require first.
- [BUG] =mail-config.el:481-484= — unconditional =org-msg-edit-mode= :after advice on replies defeats the =(reply-to-text . (text))= alternative at :459 and re-runs a major mode org-msg already set up. Gate or remove.
- [BUG] =mu4e-attachments.el:222= — the *mu4e attachments* selection buffer saves through stale MIME handles if the view changed before s — errors or saves the wrong message's parts. Check =buffer-live-p= per handle at save.
- [BUG] =mail-config.el:329= — "save attachment" in =mu4e-headers-actions= can't work from headers (MIME vars are view-buffer-local, nil in headers-mode). Drop it there.
- [BUG] =mail-config.el:282-305= — HTML view block sets variables obsolete since mu4e 1.7 (installed 1.14.1): =mu4e-view-prefer-html=, =mu4e-html2text-command= (also set twice: 186, 285), =mu4e-view-show-images=, =mu4e-view-image-max-width=. The pandoc/w3m selection never runs; shr renders regardless. Delete the dead block (image/privacy reconciliation already filed separately).
- [BUG] =mail-config.el:45-49,80-89= — top-level =(defvar message-send-mail-function nil)= pre-empts message.el's defcustom default; with msmtp absent the fallback leaves it nil → "invalid function: nil" on first send. Explicit =smtpmail-send-it= fallback or descriptive user-error.
- [UX] =mail-config.el:171,196-199= — =pick-first= + gmail listed first makes gmail the startup context though cmail reads as primary everywhere else — quiet wrong-account hazard for the first compose. Reorder contexts.
- [REMOVE] =mu4e-org-contacts-setup.el= — unreachable (nothing requires it; mail-config calls activation directly) and its featurep gate would be nil at init anyway. Delete or fold its two setqs into mail-config.
- [REMOVE] =mail-config.el:208,232= — =mu4e-starred-folder= isn't a mu4e variable (invented, no effect); =:174= =mu4e-maildir= is the obsolete alias of root-maildir set on the previous line. Drop all three.
- [REMOVE] =mu4e-org-contacts-integration.el:158,171-172= — hook surgery on =mu4e--compose-setup-completion= is a no-op on mu4e 1.14 (called directly, not via hook; already gated by the var activation sets). Delete both hook calls.
- [COVERAGE] =mu4e-attachments.el:101-105= — mid-batch save-failure path and stale-handle scenario untested.

*** TODO Findings: messengers group
From agents 2026-06-12. Beyond the standalone tasks; several feed the messenger-unification spec:
- [BUG] =signal-config.el:201= — contact cache docstring claims "cleared on signel-stop/restart"; nothing clears it (grep: fork never references it). Stale list after relink/reconnect. Advise =signel-stop= or clear on start.
- [BUG] =signal-config.el:298= — fetched-and-empty contact list is indistinguishable from cold cache (nil), so a zero-contact account re-runs the blocking fetch (up to fetch-timeout) on every C-; M m. Cache a sentinel.
- [UX] =slack-config.el:208= — =cj/slack-notify= lacks signel's hardening: no truncation (giant toasts), no sound gating, no notifications-notify fallback when the script is absent. Unification-relevant: extract a shared =cj/messenger-notify= (title prefix, truncation, sound flag, script-with-fallback) — noted in the unification spec.
- [ENHANCE] =telega-config.el:52= — telega has NO notification path (=telega-notifications-mode= not enabled); incoming Telegram messages invisible unless the buffer is on screen. Enable, or route through the shared notifier. Unification-relevant.
- [COVERAGE] — =cj/erc-join-channel-with-completion= (erc:148, four-way reconnect branching), =cj/erc-connected-servers= (would have caught the tautology), =cj/slack-notify= predicates, =cj/signel--ensure-started= branches — all untested.

*** TODO Findings: programming group
From agents 2026-06-12; spot-verified sample (prog-lsp unreachable confirmed by grep). Beyond the standalone tasks:
- [BUG→FOLD] =prog-lsp.el= — the module is UNREACHABLE: nothing requires it, so its entire LSP policy (TRAMP guard, file-watch ignores, read-process-output-max, idle-delay 0.5) is dead while prog-general.el:388-416's older conflicting block wins (idle 0.1, lsp-ui-doc on). Fold this fact into the filed "Make prog-lsp.el the single owner of generic LSP policy" task — it doesn't currently record that prog-lsp never loads.
- [BUG] =flycheck-config.el:68-70= — =checkdoc-arguments= isn't a real variable (invented name + invented format); the intended checkdoc suppression has never worked. Use =flycheck-emacs-lisp-checkdoc-variables= or drop.
- [BUG] =prog-json.el:87-90= — C-c C-q → jq-interactively binding defers to eval-after-load of jq-mode, which nothing loads — dead key. Bind in =cj/json-setup= via local-set-key (jq-interactively IS autoloaded).
- [BUG] =prog-python.el:129-132= — lsp-pyright's :hook lambda calls =lsp-deferred= unguarded on the same hook as the guarded =cj/python-setup= — pyright-absent machines still get the LSP attach prompt the guard exists to prevent. Move the require into the guarded branch; delete the hook.
- [BUG] =prog-lisp.el:122-125= — =:after (flycheck package-lint)= waits for a manual M-x to load package-lint, so =flycheck-package-setup= effectively never runs. Hook on flycheck load + require inside.
- [UX] =prog-python.el:111-115=, =prog-go.el:111-114=, =prog-webdev.el:128-147= — setup hooks attach to ts-modes only (C/shell hook both variants); grammar-unavailable fallback to classic modes silently loses indent/keys/formatter/LSP. Add classic-mode hooks.
- [UX] =prog-webdev.el:165-173= — web-mode gets the format key but none of the promised setup (no company/flyspell/LSP in HTML buffers). Add to the setup hook or fix the Commentary.
- [ENHANCE] gopls, clangd, bash-language-server, shfmt, shellcheck lack the =cj/executable-find-or-warn= load-time warnings pyright/prettier have; prog-shell's =:if (executable-find ...)= evaluates once at startup and silently disables shfmt/flycheck setup forever.
- [REMOVE] =prog-training.el:36-37= — =(url-debug t)= turns on GLOBAL url.el debug logging once leetcode loads. Debugging leftover; delete.
- [REMOVE] =prog-webdev.el:85=, =prog-json.el:44=, =prog-yaml.el:39= — three byte-identical format-region helpers. Extract one shared tested helper (system-lib).

*** TODO Findings: dev tooling group
From agents 2026-06-12; spot-verified sample. Beyond the standalone F7 task:
- [BUG] =vc-config.el:138-144= — =cj/goto-git-gutter-diff-hunks= (C-; v d) never did what it claims: consult-line over "^[+\\-]" matches source text, not gutter hunks. Build candidates from =git-gutter:diffinfos= or drop the binding (C-; v n/p covers it).
- [BUG] =dev-fkeys.el:116-122= — F4 compile+run one-shot hook installs on GLOBAL =compilation-finish-functions= before the prompt; C-g leaves it armed and the next unrelated compile triggers projectile-run-project. Use the buffer-local pattern the module already uses for cache-revert (same in =--f4-clean-rebuild-impl=:143).
- [BUG] =test-runner.el:84,222= — documented ~/.emacs.d/tests fallback doesn't exist (=cj/test-global-directory= defvar'd nil, never set); outside a project =(file-directory-p nil)= crashes in three commands. Initialize the defvar or guard with user-error. (Adds specifics to the open "Fix up test runner" task — fold.)
- [BUG] =test-runner.el:288= — focus-add prefix check lacks the trailing slash so =tests-scratch/= passes the "inside tests/" check; the correct helper =cj/test--file-in-directory-p= exists at :168 — use it.
- [BUG] =vc-config.el:217-219= — difftastic blame map binds D and S to the same command (show); D should be diff per the transient four lines down.
- [UX] =diff-config.el:37= — =ediff-diff-options "-w"= ignores ALL whitespace in every ediff session — indentation-only Python changes compare as identical. Drop the default; toggle per-session.
- [UX] =restclient-config.el:64-65= — raw global-set-key "C-; R n" hides a load-order dependency (header claims "Runtime requires: none"); use defvar-keymap + =cj/register-prefix-map= like siblings (same class as org-reveal, slack).
- [UX] =vc-config.el:196= — clipboard clone via synchronous =call-process= freezes every emacsclient frame for the whole clone. make-process + sentinel.
- [REMOVE] =vc-config.el:80-82= — phantom autoload =git-timemachine-show-selected-revision= (no such function in the package) appears in M-x and errors. Drop from :commands.
- [REMOVE] =httpd-config.el:19-30= — pointless =:defer 1= (impatient-mode loads simple-httpd on demand) + unprefixed eager globals =wwwdir=/=check-or-create-wwwdir= creating www/ on every startup. =:defer t=, prefix, or fold into markdown-config.
- [COVERAGE] — intersect/parse unit tests hand-build matching keys (the F7 bug's escape route); =--coverage-elisp-run='s compilation-finish wiring, goto-git-gutter-diff-hunks, timemachine candidate round-trip untested. F-key sweep clean: no collisions; F5 free for the debug-backend task.

*** TODO Findings: shell/term/files group
From agents 2026-06-12; spot-verified sample (eshell nested list confirmed). Beyond the standalone tasks:
- [BUG] =dirvish-config.el:37= — =cj/xdg-open= attributed to system-utils in the require-comment but defined in external-open.el; neither dirvish-config nor dwim-shell-config (caller at :876) requires it — "Direct test load: yes" headers are false. Require external-open (or move the fn into external-open-lib) + fix comment.
- [UX] =tramp-config.el:73= — =revert-without-query '(".*")= kills revert confirmation for EVERY file in Emacs, buried in the TRAMP module. Scope to =tramp-file-name-regexp= or move deliberately to an editing module.
- [UX] =dirvish-config.el:403= — quick-access entries lx (~/archive/lectures), phl (~/projects/homelab), pn (~/projects/nextjob) point at directories that don't exist on this machine. Prune or create.
- [REMOVE] =dwim-shell-config.el:474,507= — open-externally (raw xdg-open) and open-file-manager (thunar/nautilus probe chain) duplicate cj/xdg-open (dirvish o) and cj/dirvish-open-file-manager-here (f); ascii-art references jp2a, the module's only absent binary. Delete the two duplicates; install jp2a or drop ascii-art.
- [REMOVE] =tramp-config.el:115= — custom =sshfast= method referenced nowhere (everything uses sshx); =tramp-own-remote-path= added twice (:39,:128); =dirtrack-list= and =magit-git-executable "/usr/bin/git"= are unrelated globals hiding here. Prune/relocate.
- [COVERAGE] — eshell visual-commands/xterm-color wiring and the dirvish mark-all loop had no load-and-assert tests (both standalone bugs above); TRAMP perf settings look sound for the DUET latency concern (attr caching, no remote VC, direct-async + controlmaster).

*** TODO Findings: AI group
From agents 2026-06-12; spot-verified sample (string-model setq confirmed). Beyond the standalone tasks:
- [BUG] =ai-term.el:875= — close derives the tmux session name from =default-directory=, which ghostel retargets via OSC 7; after a cd the kill-session misses (orphaned agent session) or name-collides with a different aiv- session. Derive from the buffer name's immutable basename.
- [UX] =ai-term.el:827= — multi-window F9 toggle-off unconditionally delete-windows, never restoring the displaced edge-window buffer the Commentary (:24) and reuse-edge docstring (:521) promise. Restore when quit-restore still matches, or fix the docs to describe delete-window reality.
- [UX] =ai-conversations-browser.el:191= — browser load stubs =y-or-n-p= to nil, silently discarding an unsaved in-progress conversation (the direct C-; a l path offers to save). Give ai-conversations a file-arg internal instead of puppeting the interactive command via cl-letf; also the =(caar cands)= fallback loads the newest conversation on a filename mismatch — fail loudly.
- [ENHANCE] =ai-quick-ask.el:103= — dismiss mid-stream kills the buffer without =gptel-abort= — request keeps streaming to a dead buffer (wasted tokens).
- [NOTE] =ai-mcp.el= — unreachable from init, consistent with the paused Phase 1.5; add a one-line Commentary note ("not wired until Phase 2") so future audits don't re-flag, and revisit =cj/mcp-enabled-servers= defaulting to all nine servers before wiring.
- [COVERAGE] — load/autosave lifecycle untested (fresh-session load, timer self-cancel, close-buffer session-name derivation).

*** TODO Findings: media/reading group
From agents 2026-06-12; spot-verified sample (M-S- bindings, eww store split confirmed). Beyond the standalone tasks:
- [BUG] =music-config.el:585= — =cj/music-add-dired-selection= gates =dired-get-marked-files= on =(use-region-p)= — but dired marks aren't a region; marked files are ignored, + adds only file-at-point. Drop the conditional (the function already falls back correctly). Note for the EMMS-free rewrite: dirvish + shadows =dired-create-directory= — deliberate decision needed before carrying it over.
- [UX] =media-utils.el:195-204= — =cj/yt-dl-it= watches tsp (which enqueues and exits), so "Finished downloading" fires immediately while yt-dlp may fail later, silently; also affects elfeed d. Message "queued" honestly or watch the real job (tsp -f).
- [UX] =browser-config.el:34-47,171= — first-run fallback picks EWW (first, "always available") over installed real browsers; fresh machines get org links in a text browser until cj/choose-browser runs. Prefer the first external match.
- [REMOVE] =video-audio-recording.el:442-488= — =cj/recording-group-devices-by-hardware= is dead code (nothing calls it) carrying a hardcoded "Jabra SPEAK 510 USB" branch. Delete + its test file.
- [REMOVE] =calibredb-epub-config.el:198-212= — =set-auto-mode= :around advice for .epub is redundant with nov's :mode registration (auto-mode-alist wins before magic-fallback); overhead + failure surface on every file visit. Remove and verify.
- [COVERAGE] — eww interactive commands (switch-search-engine, bookmark-quick-add, copy-url) and =cj/nov-center-images= untested.

*** TODO Findings: apps/misc group
From agents 2026-06-12. Beyond the standalone tasks:
- [BUG] =hugo-config.el:49= — =cj/hugo-new-post= void-functions on =org-hugo-slug= in a fresh session (ox-hugo is :after ox, which loads on first export); =cj/hugo-export-post= already requires ox-hugo — do the same here.
- [BUG] =help-utils.el:73= — arch-wiki search signals raw file-missing when the docs dir is absent; the friendly install hint at :81 is unreachable. Guard with =file-directory-p= + user-error up front.
- [UX] =hugo-config.el:244= — eight raw global-set-key C-; h calls + hand-rolled which-key mutate cj/custom-keymap directly, against keybindings.el's own instruction. Convert to defvar-keymap + =cj/register-prefix-map= (same class as org-reveal, restclient, slack).
- [ENHANCE] =games-config.el:25= — =:defer 1= pulls malyon + 2048 into every session for nothing; use =:commands=. Also :config references =org-dir= without requiring user-constants (free-variable warning at byte-compile).
- [REMOVE] =wrap-up.el:29= — =elisp-compile-mode= doesn't exist (real mode emacs-lisp-compilation-mode derives from compilation-mode, already covered at :27); dead line. (The prior unguarded-timer fix is intact.)
- [REMOVE] =help-config.el:99-106= — stray empty :preface + dead commented Info-directory-list block. Delete.
- [NOTE] =duet-config.el= — orphaned BY DESIGN (Commentary documents pre-alpha staging; Stage 1 is the wire-in trigger). Audit record only.
- [COVERAGE] — help-config and help-utils have zero test files; the two broken paths above are exactly the untested branches.

*** TODO Findings: holistic — startup & performance
From the 2026-06-12 holistic pass; daemon init measured at 1.11s (healthy). Beyond the standalone [#A] native-comp/GC task:
- [BUG→FOLD] the eager-org chain: =org-config.el:352= org-appear has no defer trigger (only :custom) → requires all of org at init; org-agenda (=:after org :demand t=) cascades; chime's =:demand t= pulls it anyway. org-config is the most expensive require (0.229s of 1.11s). Decide fully-eager vs fully-deferred — and =init.el:146='s "calendar-sync must come after org-agenda" contract exists only as a comment (three uncoordinated writers of =org-agenda-files=). Both facts belong in the filed defer-modules task before that refactor starts.
- [PERF] =dirvish-config.el:385-387= — =:defer 0.5= defeated by :init calling autoloaded =dirvish-override-dired-mode= → dirvish fully loads at init (0.072s, third most expensive; trace-confirmed). Own the eager load or defer the override to a dired-mode-hook shim.
- [PERF] timed =:defer N= loads unused packages into every start: simple-httpd (:1s + startup mkdir despite the defer), malyon, 2048-game, emojify (may hit network), ligature. Convert to :commands/mode hooks.
- [UX] =early-init.el:235-256= — synchronous =package-refresh-contents= on the startup path when any archive cache is >7 days old (MELPA ~6MB) — multi-second network-bound start, fires in batch too. Make async post-startup or push into the localrepo update script (distinct from the filed bootstrap-relocation task).
- [PERF] =early-init.el:228= — no =package-quickstart= with 184 packages; activation walks every package dir each start (~0.3s of early-init). Free win; regenerate after package ops.
- [PERF] =prog-general.el:298= — =yas-reload-all= immediately before =yas-global-mode= scans snippet dirs twice per start (doubled "[yas] Prepared..." message). Delete the line.
- [REMOVE] cross-ref: the all-the-icons stack (already in UI core findings) is 2 of the :demand t packages plus a per-frame install-check hook.

*** TODO Findings: holistic — daemon stability
From the 2026-06-12 holistic pass. Architecture-level verdict good (timers cancelled/guarded, calendar-sync async well-contained, advice mostly named + guarded). Residual:
- [STABILITY] =transcription-config.el:293= — sentinel chain has no unwind-protect; =--append-to-log='s =insert-file-contents= signals if the log is missing → process buffer leaks, entry stuck 'running in the modeline forever, no notification. Extends the filed transcription standalone — fix together.
- [STABILITY] =calendar-sync.el:1646= — hourly timer body: fetch/parse guarded but the timezone check and =--require-calendars= run bare — any signal repeats hourly forever (the exact class fixed in four modules once). Condition-case the body; demote the hourly echo-area message to the silent log.
- [STABILITY] =music-config.el:865= — four anonymous-lambda advice in :config stack per live reload (verified: lambdas don't dedupe) and can't be advice-removed. Name the function.
- [STABILITY] =system-defaults.el:69= — =display-warning= advice appends to comp-warnings-log with no condition-case (unwritable path → every async comp warning signals from inside display-warning) and the log grows unbounded. Guard + cap.
- [STABILITY] =media-utils.el:164= — playback sentinel assumes the process buffer is alive (user killed *player:...* → sentinel error, diagnostics lost); sibling yt-dl sentinel shares the kill-buffer gap. buffer-live-p guards.
- [ENHANCE] =system-commands.el:86= — =#'ignore= sentinel + output to /dev/null makes failing lock/suspend indistinguishable from success — the user walks away from an unlocked machine. Message on nonzero exit. (Compounds the [#A] slock task: the broken lock currently fails through exactly this silent path.)
- [ENHANCE] =ui-config.el:153= — post-command cursor hook unguarded: any future signal self-removes it silently (cursor stops signaling modified/read-only until restart); frame-hook lambda also accumulates per reload. with-demoted-errors + name it.
- (kill-emacs-hook y-or-n-p prompt independently re-found here — already filed in the text/prose child; convergence noted.)

*** TODO Findings: holistic — UX consistency
From the 2026-06-12 holistic pass. Verdict: more coherent than most 120-module configs (~85% prefix-helper adoption, M-S translation fully covers its 18 bindings, F-keys collision-free, DEF-arg prompts dominate). Beyond the standalone [#A] fset task:
- [BUG] notification env gate: =transcription-config.el:169-171= gates desktop notifications on =(getenv "DISPLAY")= — an X11 predicate that works only because XWayland exports it. Use =env-gui-p= (host-environment.el provides it).
- [UX] four notification stacks beyond the messenger split (notify script ± fallback, alert.el, raw notifications-notify, echo-only for calendar-sync/recording completions). Proposed: one cj/notify facade (transcription's =cj/--notify= is the right shape) — config-wide companion to the messenger-notify addendum in the unification spec.
- [UX] five more C-; entries bypass the register helpers or lack labels: =browser-config.el:182= (C-; B, no label), =org-babel-config.el:51= (C-; k, no label), =flycheck-config.el:62-64= (:bind into cj/custom-keymap), =pearl-config.el:43= (:bind-keymap C-; L, no label), =dev-fkeys.el:533= (helper but no label). Sweep onto cj/register-prefix-map with labels.
- [UX] user-error vs message inconsistent for "nothing to act on" config-wide (examples: =custom-whitespace.el:190=, =jumper.el:202=, =chrono-tools.el:99= message; =mu4e-attachments.el:112=, =ai-rewrite.el:79= user-error; =test-runner.el:392/394= mixes both 2 lines apart). Convention: user-error when the command can't proceed; message when it ran and found nothing.
- [ENHANCE] M-S translation layer: complete for GUI (18/18) but installs only on env-gui-p paths — terminal frames have no M-uppercase route; and =dwim-shell-config.el:932/934= binds M-S-d (dired) vs raw M-D (dirvish) asymmetrically. Feeds the filed M-S review task with the concrete map.
- [ENHANCE] which-key labels: register-helper's LABEL arg used by exactly 1 of 23 registrants (rest use separate with-eval-after-load blocks); label style drifts ("X menu" vs bare nouns). Adopt LABEL arg + one style.
- [ENHANCE] "?" curated-menu candidates (for the filed convention task): elfeed search/show, dirvish, signel chat/dashboard, music playlist, ai-conversations-browser, mu4e-attachments, transcription status, pearl. calibredb remains the model.
- [UX] ="(Cancel)"= pseudo-candidate in =music-config.el:253-256= vs C-g everywhere else (90+ prompts). Drop it.
- [UX] buffer-naming drifts across three conventions (*AI-Assistant* / *Kill Ring* / *dashboard*); pick Title Case + "*Name: param*", lowercase for process logs.
- [ENHANCE] C-; f formatter shadowing implemented 3 ways (:bind :map vs local-set-key in hooks); unify on :bind. Also =keybindings.el:21= commentary still says "C-c j" for the jump prefix the code binds at C-; j.
- [ENHANCE] initial-input anti-pattern at =dwim-shell-config.el:661,680= and =erc-config.el:176-177= against the config's DEF-arg norm.

*** TODO Findings: holistic — package strategy
From the 2026-06-12 holistic pass (184 elpa dirs). Core stack modern (vertico/consult/embark/orderless, treesit-auto, built-in which-key, current magit/forge/telega/slack). Beyond the standalone gptel/prescient tasks:
- [REMOVE] true orphans, nothing references them: js2-mode, tide, json-mode (pre-treesit JS stack). package-delete + drop from .localrepo.
- [REMOVE] emojify: 2021 snapshot, dormant upstream, crashes in lui (slack disabled it), Emacs 30 renders emoji natively. Drop the use-package + hooks (=font-config.el:253=, =erc-config.el:211=); it stays on disk only as slack's declared dep.
- [BUG] legacy-mode hooks miss the ts modes: =prog-general.el:91-92= hooks =yaml-mode-hook=/=toml-mode-hook= but the config runs yaml-ts/toml-ts — general prog settings silently don't apply in YAML/TOML buffers. Rehook; delete toml-mode + eldoc-toml + yaml-mode packages (superseded by treesit).
- [RISK→FOLD] localrepo priority 200 is absolute, so package-upgrade silently no-ops on everything mirrored — the engine that fossilized emojify@2021/toml-mode@2016/js2@2023. The filed refresh-script task at [#D] deserves [#B] + a quarterly cadence, else every orphan finding regrows.
- [RISK] fork fleet sync-back stories: org-drill flip back to :vc when done (filed dev-checkout finding); auto-dim-other-buffers local checkout with :vc commented — decide its home; org-msg pins =:rev :newest= (unpinned moving target) — pin a known rev. signel/duet/pearl/wttrin/gloss/chime self-owned remotes are fine.
- [UPGRADE] wiki-summary (2018, dead upstream, predates Wikipedia's REST API; sole caller help-utils) — the audit's one write-your-own: ~30-line url-retrieve against the REST summary endpoint. Delete the package, inline the helper.
- [UPGRADE] xterm-color droppable in eshell on Emacs 30's native ansi-color (its only use; also doubly-broken per the eshell standalone task — fixing by deletion is an option).
- [ENHANCE] Python tier: poetry.el (sluggish) + pyvenv (2021) keep only if Poetry projects are still real; blacken fine until ruff-format (reformatter.el already installed). lsp-pyright current.
- [DECIDED] projectile, lsp-mode, dirvish: keep (wired into 10/7/many modules, maintained, migration cost > benefit). On the record so future audits don't relitigate.

*** TODO Findings: spin-off repos (pearl, chime, emacs-wttrin)
Full findings delivered as handoffs to each repo's inbox/ (2026-06-12-0057-from-.emacs.d-handoff-*.org); each repo's next session files them through its own value gate. Highlights:
- pearl (10 findings; suite green, 66 ERT files): auth-source negative-cache trap in pearl-clear-cache (the 2026-06-01 incident class, unfixed); sync wrapper ignores pearl-request-timeout + async has no timeout; mutation errors discard Linear's GraphQL reason; no RATELIMITED handling; dead legacy API layer (~150 lines).
- chime (10 findings; suite green; the 2026-06-11 watchdog handoff VERIFIED landed in full): lookahead vars never injected into the async child (documented feature silently capped at 8 days — one-line fix); days-until-event nil crash on mixed timed/all-day events; stale-callback race after watchdog interrupt (generation counter needed); default test run prints green integration banner over "Ran 0 tests".
- emacs-wttrin (10 findings; ~56 ERT files, CI; the face-flood reminder VERIFIED resolved — test 8f3c770 + fix c5e5e1d, reminder cleared from notes.org): no network timeouts (wttr.in stalls hang the loading buffer); error-path response-buffer leak; non-favorite cache never expires; 17 unreleased commits incl. two features — tag v0.4.0.

** PROJECT [#C] Build cj/dev-setup-project helper (per docs/specs/dev-setup-project-spec.org) :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-01
:END:
*** 2026-05-15 Fri @ 19:17:37 -0500 Specification

Interactive command that opens a review buffer with proposed per-subdirectory .dir-locals.el contents (projectile compile/run/test + cj/coverage-backend), optional starter Makefile when none exists, and gitignore updates. User edits inline, C-c C-c writes all files.

Design: [[id:596fce5d-1bab-46e7-8567-d4a2e0923091][docs/specs/dev-setup-project-spec.org]]

Scope of v1:
- modules/dev-setup-config.el (command + review-buffer major mode)
- Three-tier detection: existing Makefile, existing package.json/pyproject.toml scripts, fall-back starter Makefile generation.
- Project shapes supported: pure Elisp, pure Go, pure Python, pure Node/TS, Docker Compose polyglot.
- Re-run semantics: status banners (UNCHANGED / WILL UPDATE / WILL CREATE), idempotent gitignore append, never modifies an existing Makefile.
- ERT tests for the pure helpers (Makefile parser, package.json parser, shape detection, target-to-role mapping, review-buffer parser).

Deferred:
- Rust (Cargo.toml), Java (pom.xml), other language shapes.
- Project-wide override config file.
- Auto-detecting external run scripts in conventional locations.

Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable.

*** TODO [#B] Pure detection + parsing helpers :feature:
Implement the four pure helpers the rest of the command composes on:
- =cj/--dev-setup-parse-makefile-targets FILE= (.PHONY + bare target lines, skip pattern rules)
- =cj/--dev-setup-parse-package-json-scripts FILE= (scripts block, JSON)
- =cj/--dev-setup-detect-project-shape ROOT= (Elisp / Go / Python / Node-TS / Docker-Compose polyglot / unknown)
- =cj/--dev-setup-map-targets-to-roles TARGETS= (best-guess compile/run/test mapping per design § Detection)

Files: =modules/dev-setup-config.el= (new).  No interactive surface, no I/O
beyond reading the named file.

Acceptance: each helper callable in isolation with handcrafted fixtures;
no command yet.

Depends on: none -- start here.

*** TODO [#B] ERT coverage for the pure helpers :feature:test:
Normal/Boundary/Error tests for every helper from the prior sub-task,
matching the design's testing section.

Files: =tests/test-dev-setup-config.el=, plus
=tests/testutil-dev-setup-config.el= for the temp-project fixture builder
(writes Makefile / package.json / compose stub into =make-temp-file ... 'dir=).

Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green;
every helper has at least one Normal, one Boundary, one Error case.

Depends on: pure detection + parsing helpers.

*** TODO [#B] Starter-Makefile + .dir-locals.el proposal generator :feature:
Pure function =cj/--dev-setup-build-proposal SHAPE ROOT= returning a
structured plist of proposed blocks: one per subproject =.dir-locals.el=
(projectile compile/run/test + =cj/coverage-backend=), the optional starter
Makefile (only when none exists, adapted per shape per design § Tier 3),
and the gitignore append lines.

Files: =modules/dev-setup-config.el=.

Acceptance: given a shape plist, returns deterministic block list ready for
the review buffer; ERT cases cover each shape (Elisp / Go / Python / Node-TS
/ polyglot) plus the Tier-1 "Makefile already exists, suppress Makefile
block" branch.

Depends on: pure detection + parsing helpers.

*** TODO [#B] Review-buffer major mode + parser :feature:
Define =cj/dev-setup-review-mode= (derived from =emacs-lisp-mode=) with =C-c
C-c= / =C-c C-k= bindings, plus the pure parser
=cj/--dev-setup-review-buffer-parse CONTENTS= that turns buffer text back
into a block list.  Banner syntax per design § Review Buffer (=;; ==== <path>
====[ <status>]==, gitignore special, Makefile special).

Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=
(parser cases: well-formed multi-block, single block, empty body, missing
banner, malformed elisp inside a dir-locals block).

Acceptance: round-trip -- render proposal -> parse buffer -> equal block
list.  Mode keybindings smoke-tested.

Depends on: starter-Makefile + .dir-locals.el proposal generator.

*** TODO [#B] Writer + status diff + projectile cache reset :feature:
Implement the =C-c C-c= writer: diff each parsed block against the on-disk
file to assign =UNCHANGED= / =WILL UPDATE= / =WILL CREATE=, write only the
non-UNCHANGED ones, append gitignore idempotently, never touch an existing
Makefile, honor the =;;; cj/dev-setup-project: ignore= escape hatch, clear
projectile's per-project command cache, print the summary line.

Files: =modules/dev-setup-config.el=, plus ERT cases for the diff +
idempotent-append logic against temp dirs.

Acceptance: re-run on an unchanged project writes nothing; renaming a
Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay
untouched.

Depends on: review-buffer major mode + parser.

*** TODO [#B] Interactive command + smoke test :feature:test:
Thin =cj/dev-setup-project= interactive wrapper: resolve project root via
projectile, run detection, build proposal, render the review buffer, pop to
it.  One smoke test against a prepared temp project asserting the expected
files exist after a simulated =C-c C-c=.

Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=.  Add
=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator).

Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review
buffer; =C-c C-c= writes the expected files.

Depends on: writer + status diff + projectile cache reset.

*** TODO [#B] Resolve open questions + design follow-ups
Three design questions to close before / during implementation: (a) include
=make coverage= target in starter Makefile? (b) project-wide override file
=.cj-dev-setup.el=? (c) Cargo/pom detection.

Body: park decisions inline in the design doc or run =arch-decide= if they
turn out load-bearing.

Depends on: none, but easiest after the writer sub-task surfaces real
friction.

** PROJECT [#C] Localrepo Documentation :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-05
:END:

Audit on 2026-05-27 found the localrepo build half is shipped (=.localrepo/= holds 185 entries; =early-init.el= L135–165 wires the priority-200 pin above the local ELPA-mirror tier at 120–125 and the online fallback). The remaining "document limitations" half splits into one docs-set plus four gap-fix follow-ups that the docs cross-reference.

Docs land in three artifacts. =docs/design/localrepo.org= carries the full architecture (tier model, install path, refresh story, all four limitations with pointers to the follow-up tasks). =.localrepo/README.org= sits next to the artifact as the user-facing entry — a short summary that survives even if =early-init.el= moves. =early-init.el= grows a commentary header that points at the README, not at the design doc — the README is what future-Craig hits first.

The four limitations the docs cover (each spun out below as its own task):
- Treesitter grammars (downloaded by =treesit-auto= on first use; not in the localrepo)
- Native-comp =.eln= cache (Emacs-version-specific; invalidated by version bumps)
- System-tool deps (=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, etc.; flagged at load by =cj/executable-find-or-warn=, not packageable via =package.el=)
- Refresh / update story (no dedicated script today; ad-hoc =cp= from the elpa mirrors)
*** TODO [#C] Design doc — docs/design/localrepo.org
Write the design doc: tier model, priorities, install path, refresh story, all four limitations with cross-links to the follow-up tasks below.
*** TODO [#C] README — .localrepo/README.org
Write the README at the artifact: short prose entry point summarizing the tier model, pointing at =docs/design/localrepo.org= for full detail. This is what =early-init.el='s commentary header links to.
*** TODO [#C] Commentary header in early-init.el
Add a Commentary-section header in =early-init.el= pointing at =.localrepo/README.org= for usage and =docs/design/localrepo.org= for architecture. Sits at the top of the localrepo block (around L130).
** PROJECT [#C] Migrate from Company to Corfu (with prescient integration) :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-02
:END:

Spec: [[id:68733ba2-37a7-4a7b-bfaa-b845d82ff1e7][docs/specs/company-to-corfu-migration-spec.org]]

*** TODO [#C] Install corfu-side packages
Add corfu, cape, kind-icon, corfu-prescient to the package list. corfu-popupinfo ships inside corfu. Spec step 1.

*** TODO [#C] Rewrite selection-framework.el company block as corfu/cape stack
Replace the three company-* use-package blocks (lines 192-226) and company-prescient (240-243) with corfu / cape / corfu-popupinfo / kind-icon / corfu-prescient. Rename the section header Company → Corfu in the same change. Spec steps 2 + 8.

*** TODO [#C] Swap mail-compose completion disable to corfu
Rewrite cj/disable-company-in-mu4e-compose to (corfu-mode -1) across mu4e-compose, org-msg-edit, and message modes (mail-config.el:319-333). Spec step 3.

*** TODO [#C] Drop company-ledger for ledger's built-in capf
ledger-config.el: remove company-ledger; verify ledger-complete-at-point registers on completion-at-point-functions, add a ledger-mode-hook capf push only if it doesn't. Spec step 4.

*** TODO [#C] Drop company-auctex for AUCTeX capf + cape-tex
latex-config.el: remove company-auctex and (company-auctex-init); add cape-tex on TeX-mode-hook. Spec step 5.

*** TODO [#C] Rewire eshell completion to pcomplete capf
eshell-config.el:163-171: drop company-shell and the company-mode activation; add cape-capf-buster around pcomplete-completions-at-point + corfu-mode. Spec step 6.

*** TODO [#C] Remove company-mode calls from prog-go/python/webdev
Delete (declare-function company-mode ...) and (company-mode) from the three mode hooks; global-corfu-mode covers them. Spec step 7.

*** TODO [#C] Uninstall company packages + recompile
After the rewrite is green: package-delete company, -quickhelp, -box, -prescient, -ledger, -auctex, -shell; make clean && make compile. Spec step 9.

*** TODO [#C] Tests: corfu activation, mail-disable, capf registration
New tests/test-selection-framework-corfu.el and tests/test-mail-config-corfu-disable.el; update ledger/latex tests to assert their capf registers. Spec Testing section.

*** 2026-05-16 Sat @ 11:07:24 -0500 Goals
Drop-in replacement for the in-buffer completion stack: =company= →
=corfu=, =company-quickhelp= → =corfu-popupinfo=, =company-box= →
=kind-icon=, =company-prescient= → =corfu-prescient=, plus =cape= for
the file/keyword/dabbrev capfs that =company-files= / =company-keywords=
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 [#C] Terminal GPG pinentry Completion :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-05
:END:

Audit on 2026-05-27 found no trace of the =terminal-pinentry= branch on this machine: no local or remote ref, no reflog entry across 732 entries reaching back through January, no stash, no dangling commit, no sibling worktree. The 2026-01-24 session log says the branch was created that day, but the work either lived on another machine or was deleted before reaching here. The original task above (=Finish terminal GPG pinentry configuration=) is superseded by this one.

Surviving footprint on this machine: one commented line at =modules/auth-config.el:83= (=;; (setq epa-pinentry-mode 'loopback)=). The hook point =env-terminal-p= exists in =modules/host-environment.el:97=. Everything else (terminal-vs-GUI branching in the epa =:config=, external pinentry wiring for GUI, =GPG_TTY= export, tests) is to be written fresh off main.

Goal: in terminal Emacs, GPG passphrase prompts land in the minibuffer via loopback mode; in GUI Emacs, prompts go to the existing external pinentry.

Open: confirm the GUI pinentry tool (2026-01-24 notes named =pinentry-dmenu=; current =auth-config.el= names no pinentry program, leaving it to =gpg-agent='s config). Also worth checking whether the =terminal-pinentry= branch survives on the laptop and should be pulled here rather than rewritten.

*** TODO [#C] env-terminal-p branch in epa :config :feature:
Inside the epa =use-package= =:config= in =modules/auth-config.el=, set =epa-pinentry-mode= to ='loopback= when =(env-terminal-p)=, else leave the external pinentry path active. Replace the lone commented line at =auth-config.el:83=.

*** TODO [#C] GPG_TTY export for terminal sessions :feature:
When =(env-terminal-p)=, =(setenv "GPG_TTY" (shell-command-to-string "tty"))= so gpg-agent can target the controlling tty. Guard against a non-tty stdin.

*** TODO [#C] gpg-agent updatestartuptty refresh in terminal :feature:
The current =call-process= to "gpg-connect-agent updatestartuptty /bye" runs unconditionally; keep it for GUI, and re-fire it on terminal entry so the agent re-binds to the current tty.

*** TODO [#C] ERT tests for terminal vs GUI pinentry branching :test:
Test that with =env-terminal-p= stubbed t, =epa-pinentry-mode= resolves to ='loopback= after =auth-config= loads; with it stubbed nil, the loopback setting is not applied. Use =cl-letf= around =env-terminal-p=; cover normal, boundary (=epa= already loaded), error (=gpg-connect-agent= missing).

*** TODO [#C] Minibuffer prompt in real terminal Emacs
=emacs -nw=, open an encrypted file or trigger an auth-source decrypt, confirm the passphrase prompt lands in the minibuffer rather than failing on missing pinentry.

*** TODO [#C] External pinentry still fires in GUI Emacs
Restart the daemon, open a GUI frame, trigger an encrypted decrypt, confirm =pinentry-dmenu= (or whatever GUI pinentry is configured) still appears.

*** TODO [#C] Archive the original L3813 task
After this work lands, mark the original "Finish terminal GPG pinentry configuration" task DONE with a =CLOSED:= stamp and a one-line note pointing at this parent task.

** DOING [#C] google-keep in-editor integration — build, module-to-package :feature:
v1 (read-only) implemented and tested (Phases 1-3): the gkeepapi Python bridge (=scripts/google-keep/keep-bridge.py=, 12 tests), the elisp core + =cj/keep-refresh= renderer with atomic writes and async make-process (=modules/google-keep-config.el=, 15 ERT tests), un-orphaned under a =C-c k= prefix, graceful warning when gkeepapi/token/auth is missing. The pure JSON-to-org core is kept extractable per the spec. Live fetch needs the one-time gkeepapi + master-token setup — see "Google Keep v1 live setup and first fetch" under Manual testing and validation.
Next: v2 (read-write — create/edit back to Keep, with a staleness guard) per the spec, the immediate follow-on once the live read is confirmed. Later: list/checkbox rendering, package extraction.
Spec: [[file:docs/specs/google-keep-emacs-integration-spec.org][google-keep-emacs-integration-spec.org]] (Ready, 2 review rounds; all five decisions resolved 2026-06-25).
Offline (from the roam inbox, "pocketbook" framing): make the integration usable without network — a local cache of fetched notes for offline read, and queued writes replayed on reconnect. Folds the standalone "a Google Keep integration that works offline" idea into v2+ scope.
** TODO [#D] Slack message buffers in a reused popup window :quick:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-25
:END:
Display slack.el message and thread buffers in a dedicated popup window (side or bottom) and reuse that one window instead of spawning a new window per buffer. Likely a =display-buffer-alist= rule (or popper integration) in =modules/slack-config.el=. Status (2026-06-25): =cj/slack--display-buffer= already reuses one non-selected window; the remaining piece is a *dedicated* side/bottom window. Craig's call — keep the current reuse behavior for now and fold the dedicated-window placement into the "Unified popup and messenger UX" work (same window-placement decision should cover Slack, not be solved piecemeal here).

** TODO [#D] Theme Studio nerd-icons vNext follow-ups :feature:
Deferred from [[file:docs/specs/theme-studio-nerd-icons-colors-spec.org][theme-studio-nerd-icons-colors-spec.org]]: extend the legend to
buffer-mode and command/symbol categories if the file set proves insufficient;
add a "reset to nerd-icons native palette" button.
** TODO [#D] Dashboard over-scroll: pin last line to window bottom :bug:
:PROPERTIES:
:LAST_REVIEWED: 2026-05-22
:END:
Triggered by: 2026-05-20 Dashboard buffer too long follow-up.

After the opens-at-top fix (=4ac1b81=), the dashboard can still be
scrolled past its content: the banner image makes the buffer just over
one screenful, so the wheel / =C-v= / =M->= pull the last line up and
leave empty space below it.  Craig wants scrolling to stop once the
trailing line reaches the window bottom (no void) while still allowing
scroll-down to reach content below the window.

Findings from the 2026-05-20 investigation:
- =pixel-scroll-precision-mode= is off, so this is standard line-based
  scroll overshoot (the tall banner image inflates the rendered height).
- A =window-start= clamp does not work: =window-start= only lands on
  line boundaries, so it can't express a position partway into the
  banner image — it either blocks all scrolling or leaves the void.
- A =recenter -1= pin on =post-command-hook= does not work: it fires on
  every command, so it fights item navigation (the cursor can't reach
  the projects / bookmarks / recents).
- Right design: clamp only on actual scroll commands — advise
  =mwheel-scroll= / =scroll-up-command= / =scroll-down-command= /
  =end-of-buffer= to =recenter -1= when over-scrolled, never on
  navigation commands.
- Live experiment scratch file: =~/dashboard-overscroll-experiment.el=.

** TODO [#D] Emacs Packages — Curl-Friendly Web Service Wrappers
Ideas for new Emacs packages following the same pattern as wttrin: HTTP GET to a simple web service, render results in a buffer, optionally show summary in the mode-line. All of these share the async fetch + caching infrastructure already proven in wttrin.
Captured On: [2026-04-04 Sat]
*** TODO Stock Market / Finance Package (Finnhub or Alpha Vantage)
Build a stock watchlist and quote viewer for Emacs. User defines a list of symbols; package fetches quotes and renders a formatted table in a dedicated buffer. Optional mode-line ticker showing one or more symbols rotating on a timer.

**** Features
- Customizable watchlist: user defines a list of stock symbols in a defcustom; package fetches and displays all of them in a single buffer
- Formatted quote table: symbol, company name, current price, daily change (absolute and percent), volume — color-coded green/red for gains/losses
- ASCII sparkline charts: inline mini-charts showing intraday or multi-day price movement using Unicode block characters (▁▂▃▅▇ style)
- Mode-line ticker: rotating display of one or more symbols with price and change indicator, similar to wttrin's weather widget — click to open the full watchlist buffer
- Detail view: press RET on a symbol to see extended data — open/high/low/close, 52-week range, market cap, P/E ratio (data availability depends on backend)
- Auto-refresh with market awareness: background timer fetches new data during market hours; pauses on weekends and after-hours to conserve API calls
- Unit/currency preference: display prices in local currency if the backend supports it
- Cache layer: same pattern as wttrin — serve cached data instantly, refresh in background, show staleness indicator when data is old
- Interactive symbol lookup: ~M-x stock-add-symbol~ with completion against a symbol database or search endpoint

**** What you'd learn
- JSON parsing in elisp (~json-parse-buffer~, ~json-read~) — these APIs return JSON, not plain text, so this is the main new skill vs. wttrin
- ASCII chart rendering — drawing sparklines or simple price charts with Unicode block characters in a buffer
- API key management in elisp — storing keys in ~auth-source~ or custom variables, passing them as query params

**** Where the complexity lives
- Rendering: No pre-formatted ASCII comes back from the API. You'd build the table layout and any chart visualization yourself. This is the bulk of the work.
- Market hours awareness: Knowing when to fetch (pre-market, regular, after-hours, weekends) to avoid wasting API calls.
- Rate limiting: Free tiers are tight. Finnhub gives 60 calls/min which is generous; Alpha Vantage gives only 25/day on the free tier. Caching strategy matters more here than in wttrin.

**** Candidate backends
- Finnhub (finnhub.io): Free API key, 60 calls/min, real-time US quotes. JSON only. Best rate limit of the free options.
- Alpha Vantage (alphavantage.co): Free API key, 25 calls/day. Supports CSV output which is trivial to parse — no JSON needed. Good for daily summaries, bad for frequent polling.
- Twelve Data (twelvedata.com): Free key, 800 calls/day, 8/min. Covers stocks, forex, crypto, ETFs. JSON and CSV.

**** Downsides
- API key requirement adds friction for users (signup, config). Not as frictionless as wttrin.
- Rate limits mean you can't poll aggressively. Stale data is the norm on free tiers.
- Financial APIs change or shut down. Yahoo Finance's unofficial API has broken repeatedly over the years. Even paid services deprecate endpoints. Expect maintenance.
- Finnhub and Alpha Vantage are US-market-centric. International coverage varies.

**** Effort: Medium-High
The fetch/cache layer is straightforward (reuse wttrin patterns). The rendering layer (tables, charts, color-coding gains/losses) is where most of the time goes. Expect this to be a real project, not a weekend hack.

**** Name candidates (backronyms)
Pick one. All are recursive (self-referential) in the style of CHIME.
- BULL — *BULL Updates Live Listings*
- MINT — *MINT Indexes Noteworthy Tickers*
- QUOTE — *QUOTE Updates Ongoing Ticker Estimates*
- ASSET — *ASSET Surfaces Stock Exchange Tickers*
- MOAT — *MOAT Monitors Active Tickers*
- TRADE — *TRADE Reveals Active Daily Equities*
- BELL — *BELL Exhibits Live Listings*
- CHART — *CHART Highlights Asset Rate Tickers*
- BOARD — *BOARD Oversees Asset Rate Data*
- VAULT — *VAULT Aggregates Underlying Listing Tickers*

*** TODO rate.sx Wrapper — Cryptocurrency Rates
Wrap Igor Chubin's rate.sx service. This is the lowest-effort, highest-pattern-match option — rate.sx works exactly like wttr.in. Returns colored ASCII tables with sparkline charts. Same ~User-Agent: curl~ trick, same ANSI escape codes.

**** Features
- Full crypto dashboard: ~M-x rate-sx~ opens a buffer with a colored ASCII table of top cryptocurrencies — name, price, 24h change, market cap, and sparkline charts — all rendered by the service
- Single coin lookup: ~M-x rate-sx-coin~ prompts for a coin name (e.g., ~eth~, ~btc~) and displays its detailed view
- Plain price fetch: query ~rate.sx/1BTC~ to get a single numeric price — useful for mode-line display or programmatic use from other elisp
- Mode-line widget: show the price of one or more coins in the mode-line with periodic background refresh, similar to wttrin's weather indicator
- Customizable coin list: user picks which coins appear in the dashboard via a defcustom
- Currency base selection: rate.sx supports displaying prices in different fiat currencies
- ANSI color rendering: reuse wttrin's ~xterm-color~ pipeline to convert the service's colored ASCII output into Emacs faces
- Cache with background refresh: same timer-based pattern as wttrin — data stays warm, buffer opens instantly

**** What you'd learn
- Very little new — this is almost a copy of wttrin with different URL construction. Good first project if you want to validate the pattern before tackling stocks.
- Could explore sharing infrastructure between wttrin and this package (common async fetch, caching, ANSI rendering).

**** Where the complexity lives
- Minimal. The service does the formatting. Your job is URL construction, fetch, ANSI-to-faces conversion (already solved in wttrin via ~xterm-color~), and buffer display.
- Coin selection UX: letting users pick which coins to show, custom vs. top-N, etc.

**** Downsides
- Single point of failure: rate.sx is one person's side project. If Chubin takes it down, the package is dead. No fallback.
- Crypto-only. No traditional stocks, forex, or commodities.
- Less useful than a stock package for most people.

**** Effort: Low
Could reuse 70-80% of wttrin's code. A weekend project if you're focused.

*** TODO Frankfurter Currency Exchange Package
Wrap the Frankfurter API (frankfurter.dev) for fiat currency conversion and historical rates. ECB data, open source, no API key.

**** Features
- Quick conversion: ~M-x currency-convert~ prompts for amount, base currency, and target currency — displays the result in the echo area (e.g., "100 USD = 91.34 EUR")
- Multi-target conversion table: convert one amount against several currencies at once, rendered as an aligned table in a dedicated buffer
- Historical rate lookup: query a specific date's exchange rate — useful for expense reports, invoicing, or curiosity
- Rate trend view: fetch a date range and display a table or ASCII sparkline showing how a currency pair moved over days/weeks/months
- Latest rates dashboard: ~M-x currency-latest~ shows today's rates for a user-defined set of currency pairs in a buffer
- Interactive currency selection: completing-read over the ~30 supported currencies with full names (e.g., "USD — United States Dollar")
- Mode-line rate display: optionally show one currency pair's rate in the mode-line with daily background refresh
- Cache layer: rates only update once per business day, so caching is especially effective — fetch once, serve all day

**** What you'd learn
- JSON parsing in elisp (the API returns JSON, not formatted text)
- Table rendering — building aligned currency tables with ~format~ and text properties
- Historical data display — the API supports date ranges, so you could show rate trends over time

**** Where the complexity lives
- Rendering: You'd build the table and any trend visualization yourself.
- Date handling in elisp for historical queries (~encode-time~, ~format-time-string~, etc.).
- UX: interactive base/target currency selection with completion.

**** Downsides
- ECB data updates once per business day. No real-time rates — this is reference data, not trading data.
- Covers ~30 currencies (major fiats). No crypto, no exotic currencies.
- Frankfurter is open-source and self-hostable, which is good for longevity, but the public instance could still go away.

**** Effort: Low-Medium
JSON parsing adds a step vs. wttrin's plain text, but the API is clean and well-documented. Straightforward project.

*** TODO ipinfo.io — IP and Geolocation Lookup
~curl ipinfo.io~ returns JSON with your public IP, city, region, country, ISP, and timezone. No auth needed for basic lookups (1000 requests/day unauthenticated).

**** Features
- My IP: ~M-x ipinfo~ fetches your public IP and geolocation, displays a formatted summary in a buffer or the echo area — IP, city, region, country, ISP, timezone, coordinates
- Arbitrary IP lookup: ~M-x ipinfo-lookup~ prompts for an IP address and shows the same geolocation detail
- Copy IP to kill ring: one-keystroke convenience for grabbing your public IP
- Open in browser map: command to open the returned lat/long coordinates in OpenStreetMap or Google Maps via ~browse-url~
- Hostname resolution: the API also returns the reverse DNS hostname for an IP
- Mode-line IP display: optionally show your current public IP in the mode-line (useful when switching between networks/VPNs)
- Org-mode integration: insert IP/geo info as an org property block or table row at point

**** What you'd learn
- Minimal new skills — simple JSON response, single fetch, render in buffer or echo area.
- Could add map integration (open coordinates in browser or an Emacs map package).

**** Where the complexity lives
- Almost nowhere. This is the simplest possible package. Fetch JSON, format it, display it.
- If you want to look up arbitrary IPs (not just your own), add a prompt with completion history.

**** Downsides
- Very niche utility. You look up your IP occasionally, not daily.
- Free tier is generous (1000/day) but authenticated lookups require a token for enriched data.
- Privacy-conscious users may not want to send their IP to a third party (though they already do by virtue of connecting).

**** Effort: Very Low
An afternoon project. Good as a learning exercise for the fetch-parse-render pattern if you haven't done JSON APIs in elisp before.

*** TODO icanhazdadjoke.com — Dad Jokes in Emacs
~curl -H "Accept: text/plain" https://icanhazdadjoke.com~ returns a single plain-text joke. No auth, no key, no rate limit concerns for casual use.

**** Features
- Random joke: ~M-x dad-joke~ fetches a random joke and displays it in the echo area — minimal disruption, maximum groan
- Joke buffer: ~M-x dad-joke-buffer~ opens a dedicated buffer with a joke, nicely formatted with a large font face. Press ~n~ for the next joke, ~q~ to quit
- Search jokes: ~M-x dad-joke-search~ prompts for a term (e.g., "cat") and displays matching jokes in a buffer — the API supports ~?term=~ search
- Startup joke: optional hook to display a dad joke in the echo area or scratch buffer on Emacs startup
- Org-mode insertion: ~M-x dad-joke-insert~ inserts a joke at point — for lightening up documentation or commit messages
- Kill ring: ~M-x dad-joke-yank~ fetches a joke and puts it directly in the kill ring for pasting elsewhere

**** What you'd learn
- Nothing technically new — this is the simplest possible HTTP-GET-to-buffer pattern.
- Good excuse to experiment with fun presentation: display in echo area, dedicated buffer, or even as a startup message.

**** Where the complexity lives
- It doesn't. Fetch a string, display it. The API also supports search (~?term=dog~) if you want to add that.

**** Downsides
- Toy project. Zero practical utility beyond morale.
- The joke quality is... dad jokes.

**** Effort: Trivial
An hour, maybe two if you add search and a nice buffer layout. Publishable on MELPA as a novelty package.

*** TODO qrenco.de — QR Code Generator
Chubin's QR code service. ~curl qrenco.de/hello~ returns a QR code rendered in Unicode block characters. Encodes arbitrary text, URLs, WiFi credentials, etc.

**** Features
- Encode text: ~M-x qr-encode~ prompts for a string and displays the QR code in a dedicated buffer using Unicode block characters
- Encode region: ~M-x qr-encode-region~ encodes the currently selected text — quick way to QR-ify a URL, password, or snippet
- Encode URL at point: ~M-x qr-encode-url~ detects the URL under point (via ~thing-at-point~) and generates a QR code for it
- WiFi QR codes: ~M-x qr-wifi~ prompts for SSID, password, and encryption type, then generates the standard WiFi QR format (~WIFI:T:WPA;S:MyNetwork;P:password;;~) — scan to join a network
- Buffer font management: automatically sets the buffer to a monospace font with consistent Unicode block rendering (same approach as wttrin's Liberation Mono override)
- Copy as text: yank the QR code's block characters to the kill ring for pasting into emails, READMEs, or chat
- Adjustable size: the service supports size parameters — expose this as a prefix argument or defcustom

**** What you'd learn
- Handling Unicode block character output (not ANSI colors this time, but character-level rendering)
- Interactive input patterns — prompting for text to encode, or encoding the current region/URL at point

**** Where the complexity lives
- Font and character width: QR codes require a monospace font where the block characters render at consistent widths. Some Emacs font configurations break this. You'd need to set the buffer font explicitly (like wttrin does).
- The service sometimes returns ANSI codes for inverted colors. May need ~xterm-color~ or manual processing.

**** Downsides
- Same single-point-of-failure risk as rate.sx — one person's service.
- QR codes in a terminal/buffer are inherently lower resolution than image-based ones. Scanning reliability depends on terminal font size and screen.
- Niche use case. Most people generate QR codes infrequently.

**** Effort: Low
Similar to rate.sx in scope. The fetch is trivial; font handling and display are the main considerations.

*** TODO dns.toys — Multi-Tool Utility via DNS
dns.toys answers queries over DNS instead of HTTP. ~dig 100USD-EUR.fx @dns.toys~ returns currency conversion, ~dig mumbai.time @dns.toys~ returns world time, ~dig 42km-mi.unit @dns.toys~ does unit conversion. Also supports base conversion, math constants, and more.

**** Features
- Currency conversion: ~M-x dns-toys-currency~ prompts for amount and currency pair (e.g., "100 USD to EUR"), displays result in echo area
- World time: ~M-x dns-toys-time~ prompts for a city name and shows the current local time — faster than searching online, no browser needed
- Unit conversion: ~M-x dns-toys-unit~ prompts for a value and unit pair (e.g., "42 km to mi"), returns the conversion
- Base conversion: ~M-x dns-toys-base~ converts between decimal, hex, octal, and binary (e.g., "100 dec to hex")
- Math constants: ~M-x dns-toys-constant~ looks up pi, e, tau, etc. — niche but handy in a calc session
- Unified command: ~M-x dns-toys~ with a smart prompt that detects query type from input format, dispatching to the right DNS query automatically
- Echo area results: all results display in the echo area by default for quick non-disruptive answers, with an optional dedicated buffer for history
- Async queries: use ~start-process~ with sentinels so ~dig~ calls don't block Emacs

**** What you'd learn
- Calling external processes from elisp (~call-process~ or ~start-process~ to invoke ~dig~) instead of ~url-retrieve~. This is a meaningfully different integration pattern from wttrin.
- Parsing DNS TXT record output — dig returns structured but noisy output; you'd extract the answer section.
- Building a multi-function package — this one service covers currency, time, units, and base conversion, so the UX needs a dispatch mechanism (separate commands, or a unified prompt with type detection).

**** Where the complexity lives
- Output parsing: ~dig~ output is not designed for human consumption. You'd parse the ANSWER SECTION, strip TTL/class/type fields, and extract the payload string.
- Latency: DNS queries are fast but ~call-process~ on ~dig~ has subprocess overhead. For interactive use this is fine; for mode-line updates you'd want async (~start-process~ with a sentinel).
- Feature breadth: The temptation is to wrap every dns.toys feature. Scoping to a focused set (currency + time + units) keeps it manageable.

**** Downsides
- Requires ~dig~ installed (standard on Linux/macOS, not on Windows). Limits portability.
- dns.toys is a single maintainer's project. Same fragility concern as rate.sx and qrenco.de.
- DNS protocol means no rich formatting — just short text strings. The results are useful but visually plain.
- Some networks/firewalls block non-standard DNS queries, which would silently break the package.

**** Effort: Low-Medium
The individual queries are trivial. The interesting work is building a clean multi-function UX and handling the process-based (vs. HTTP-based) integration pattern. Good project for learning elisp process management.

*** TODO cheat.sh Integration — Programming Cheat Sheets
~curl cheat.sh/tar~ returns a syntax-highlighted cheat sheet. Supports language-specific queries like ~cheat.sh/python/lambda~. Already has some Emacs integrations (cheat-sh.el exists) but could be worth a custom implementation if existing packages don't fit your workflow.

**** Features
- Quick lookup: ~M-x cheat-sh~ prompts for a topic (e.g., "tar", "git/stash") and displays a syntax-highlighted cheat sheet in a dedicated buffer
- Language-scoped queries: ~M-x cheat-sh-lang~ prompts for language then topic (e.g., ~python/lambda~, ~go/goroutine~) with two-stage completion
- Context-aware lookup: detect the current buffer's major mode and scope the query to that language automatically — in a Python buffer, querying "lambda" goes to ~cheat.sh/python/lambda~
- ANSI-to-faces rendering: convert the service's syntax-highlighted ANSI output to proper Emacs font-lock faces using ~xterm-color~ (same pipeline as wttrin)
- Navigation: browse related topics from within the buffer — follow-up queries without returning to the minibuffer. Previous/next topic history with ~p~ / ~n~
- Completion against the topic list: fetch and cache ~cheat.sh/:list~ to provide completing-read over all available topics
- Offline cache: optionally cache previously viewed cheat sheets for offline access or instant re-display
- Region query: select a command or function name and look it up directly with ~M-x cheat-sh-region~

**** What you'd learn
- ANSI syntax highlighting → Emacs faces (same skill as wttrin)
- Deep completion support: cheat.sh has a massive topic tree. Building good interactive completion for ~cheat.sh/{language}/{topic}~ is a UX challenge.

**** Where the complexity lives
- Completion and navigation: the value is in making it fast to find the right cheat sheet. ~cheat.sh/:list~ returns thousands of entries.
- Existing packages: ~cheat-sh.el~ already exists on MELPA. You'd need a reason to build your own (better caching, offline support, integration with your workflow).

**** Downsides
- Overlaps with existing Emacs packages. Check ~cheat-sh.el~ before building.
- The service aggregates from many sources. Quality is inconsistent across topics.

**** Effort: Medium
If building from scratch. Low if extending or wrapping an existing package. The completion UX is where the effort goes.
** TODO [#D] Localrepo refresh / update script :feature:
No dedicated update path today — refreshing a pinned package means ad-hoc =cp= from the local elpa mirrors. Document the current shape and decide whether a =scripts/refresh-localrepo.sh= is worth writing. Cross-linked from =docs/design/localrepo.org=.

** TODO [#D] Native-comp .eln cache strategy :feature:
The native-comp =.eln= cache is Emacs-version-specific; an Emacs upgrade invalidates everything. Document the cache location, what an upgrade triggers, and whether a warm-the-cache script is worth shipping. Cross-linked from =docs/design/localrepo.org=.

** TODO [#D] Polish reveal.js presentation setup :feature:

Three small reveal.js improvements; collected into one task because each on its own is too small to track separately.

1. *Image insertion helper.* Function to insert images with proper org-reveal attributes (sizing, background images, etc.) without having to remember the syntax.
2. *Default font sizing for slide elements.* Configure reveal.js font sizes for headings, body text, code blocks, etc. — better defaults via =org-reveal-head-preamble= CSS or a custom theme.
3. *Custom dupre reveal.js theme.* CSS theme using the colors from =themes/dupre-palette.el=. Install into =reveal.js/css/theme/= for use with =#+REVEAL_THEME: dupre=.

** TODO [#D] System-tool dependency install script :feature:
=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, and other binaries that =cj/executable-find-or-warn= flags at module load are not in =package.el='s reach. Document the required-tool set and ship a setup script (or =pacman=/=apt= invocation set). Cross-linked from =docs/design/localrepo.org=.

** TODO [#D] Treesitter grammar offline cache :feature:
Treesitter grammars are downloaded by =treesit-auto= on first use and live outside the localrepo. For true offline reproducibility, cache the grammars next to the localrepo (a =.localrepo/treesitter/= tier, or a separate mirror script). Cross-linked from =docs/design/localrepo.org=.

** TODO [#C] Webm previews not rendering in dirvish :bug:solo:
Dirvish computes a valid MD5-hashed cache path and =ffmpegthumbnailer= thumbnails the webm fine by hand, but dirvish's async cache generation never lands the jpg, so no preview shows. Root-cause the async step: trace the =(cache . CMD)= recipe dispatch and sentinel (=dirvish-shell-preview-proc-s=, =dirvish--make-proc=) to find why the generated jpg is never written or displayed.

** TODO [#C] Completion category for the mu4e attachment picker :feature:solo:
The Save-attachment picker (=mu4e-attachments.el=) has bare candidates worth a category. Add a custom category plus a table annotation-function showing each attachment's MIME type and size; confirm the mu4e part-plist keys first. Helper =cj/completion-table-annotated= is in =system-lib=.

** TODO [#D] Claude Code unterminated-color bleed (upstream)
Claude Code truncates a colored span without a reset, so the color bleeds down the EAT buffer. The newline-reset workaround (=cj/eat-reset-sgr-at-newline=) contains the streaming case but not cursor-positioned / full-screen rendering, and a full EAT-side fix would break legitimate cross-line color. The clean fix is upstream -- report it to Claude Code with a minimal repro.

** TODO [#D] occur/xref font-lock coloring watch :bug:
=occur= and =xref= enable font-lock themselves, not via =global-font-lock-mode=, so the exclusion fix does not apply and they show source-line fontification on purpose. No action unless a result ever renders with colors that do not match its source buffer, in which case investigate the real mechanism.

** PROJECT [#B] Structural organization followups from 2026-06-28 review :refactor:
These are the structural findings from the 2026-06-28 Elisp organization
review that were not already represented in =todo.org=. The already-tracked
architecture items were intentionally excluded: eager =init.el= load graph,
module deferral/autoloads, utility consolidation, keymap registration,
which-key label drift, music/VAMP extraction, and known =dwim-shell= /
=external-open= duplicates.

*** 2026-06-29 Mon @ 05:35:09 -0400 Split calendar-sync.el into ics/recurrence/org/source layers
Landed: commit 54250d95 — split into a thin public face plus calendar-sync-{ics,recurrence,org,source}.el; every function moved verbatim, public names unchanged; all 574 calendar-sync tests + the full 5390-test suite green; both header gates pass with the 4 new modules in the load-graph allowlist. Acceptance checks met: tests pass, =(require 'calendar-sync)= loads clean, parser/recurrence tests reach their layer through the require chain, C-; g and public names unchanged. Original task spec retained below as the record.
Location: =modules/calendar-sync.el=.

Issue: =calendar-sync.el= is the largest active module in the config
\(~1,782 lines, ~105 definitions\). It combines several distinct concerns:
- module config and persistent sync state near =calendar-sync-calendars= and
  =calendar-sync--state-file=;
- timezone/date utilities such as =calendar-sync--add-months=,
  =calendar-sync--add-days=, =calendar-sync--format-timezone-offset=;
- ICS text parsing and property extraction such as
  =calendar-sync--normalize-line-endings=, =calendar-sync--unescape-ics-text=,
  =calendar-sync--get-property=, =calendar-sync--parse-event=;
- recurrence and exception handling such as
  =calendar-sync--parse-rrule=, =calendar-sync--expand-recurring-event=,
  =calendar-sync--collect-recurrence-exceptions=;
- external fetch / conversion orchestration for =:fetcher 'ics= and
  =:fetcher 'api= calendars;
- Org rendering and agenda-facing commands such as =calendar-sync--event-to-org=,
  =calendar-sync-now=, =calendar-sync-start=, and keymap setup.

The file is internally sectioned, but changing one concern still requires
loading and navigating the whole parser/fetch/render stack. Tests also have to
target one very broad module, so failures do not naturally point at one owner.

Fix shape:
- Keep =calendar-sync.el= as the public entry point, user options, commands,
  timer lifecycle, and keymap.
- Extract a dependency-light parser module, e.g. =calendar-sync-ics.el=, for
  line normalization, property lookup, text cleanup, timestamp parsing, attendee
  parsing, and event parsing.
- Extract recurrence logic to =calendar-sync-recurrence.el=:
  RRULE parsing, date math, expansion, EXDATE filtering, RECURRENCE-ID
  exception collection/application.
- Extract source/fetch state to =calendar-sync-source.el= or
  =calendar-sync-fetch.el=: secret URL resolution, API helper invocation,
  curl/process execution, per-calendar state persistence.
- Extract Org output to =calendar-sync-org.el=: org-safe heading/body/property
  rendering and final file write.
- Leave a compatibility layer in =calendar-sync.el= requiring the pieces and
  exporting the existing public commands; avoid renaming public functions unless
  tests prove all callers are migrated.

Acceptance checks:
- Existing calendar-sync unit and integration tests still pass.
- =emacs --batch -Q -L modules --eval "(require 'calendar-sync)"= either loads
  cleanly or fails only for a documented external dependency.
- Parser/recurrence tests can require their extracted modules without starting
  timers, reading private config, or touching the network.
- The public command names and =C-; g= behavior remain unchanged.

*** 2026-06-29 Mon @ 05:35:09 -0400 Split video-audio-recording.el into devices + capture layers
Landed: commit c1227a36 — split into a thin public face plus video-audio-recording-{devices,capture}.el; every function moved verbatim, public names unchanged; all 323 video-audio tests + the full 5390-test suite green; both header gates pass. Settled on devices+capture+top rather than the proposed device/process/ui split: config and the diagnostic/test/UI commands stay in the public top module, and the engine is one acyclic layer (no call crosses up into top, so zero forward-declared functions). Acceptance checks met: tests pass, device tests can require only the devices layer, command-construction tests only the capture layer, C-; r names/behavior unchanged. Original task spec retained below as the record.
Location: =modules/video-audio-recording.el=.

Issue: =video-audio-recording.el= is a broad workflow module
\(~1,110 lines, ~53 definitions\). It currently owns all of these in one file:
- user options and process state;
- modeline indicator;
- external dependency checks for =ffmpeg= and =wf-recorder=;
- PulseAudio/PipeWire discovery and parsing, including
  =cj/recording--parse-pactl-sources-verbose=,
  =cj/recording--parse-pactl-sinks-verbose=,
  =cj/recording--get-sink-apps=;
- device labels, sorting, and =completing-read= UI;
- short device test recordings and playback;
- validation/auto-fix of stale system-audio monitors;
- ffmpeg / wf-recorder command construction;
- process start/stop/sentinel lifecycle;
- public commands and keymap registration.

The section headers make the file navigable, but the ownership boundary is too
wide. A device-label bug, an ffmpeg command regression, and a modeline/process
bug all land in the same module, even though the risk and test shape differ.

Fix shape:
- Keep =video-audio-recording.el= as the public command/keymap entry point and
  top-level defcustom home.
- Extract device discovery/parsing to =video-audio-recording-devices.el=:
  pactl parsers, source/sink availability, device status labels, sink-app
  lookup, default monitor resolution.
- Extract command construction and process lifecycle to
  =video-audio-recording-process.el=: build audio/video commands, start
  processes, sentinel, graceful shutdown, wait-for-exit.
- Extract setup/test UI to =video-audio-recording-ui.el=: labeled
  =completing-read= tables, quick setup, manual selection, active-audio display,
  short test recordings.
- Leave modeline integration either in the public module or in a tiny
  =video-audio-recording-modeline.el= if it grows further.

Acceptance checks:
- Existing =test-video-audio-recording-*.el= files still pass after moving
  requires/imports.
- Device parser tests can require only the device module and do not load keymaps
  or process start code.
- Command-construction tests can require only the process module and do not call
  =pactl=, =ffmpeg=, or =completing-read=.
- Public commands under =C-; r= keep their current names and behavior.

*** TODO [#B] Split ai-term.el into project/session, display, backend, and command layers :refactor:
Location: =modules/ai-term.el=.

Issue: =ai-term.el= is now the AI-agent terminal package rather than a small
launcher. It is ~1,205 lines and mixes four separate systems:
- project discovery and candidate ordering:
  =cj/--ai-term-candidates=, =cj/--ai-term-project-root-p=,
  =cj/--ai-term-sort-candidates=, =cj/--ai-term-format-candidate=;
- tmux session naming and live-session discovery:
  =cj/--ai-term-tmux-session-name=, =cj/--ai-term-live-tmux-sessions=,
  =cj/--ai-term-session-active-p=, =cj/--ai-term-launch-command=;
- display/window geometry policy:
  =cj/--ai-term-reuse-existing-agent=, =cj/--ai-term-reuse-edge-window=,
  =cj/--ai-term-display-saved=, display-buffer rule setup, toggle-off
  restore/swap behavior;
- EAT backend/process interaction:
  =eat= creation, =eat-buffer-name= binding, pty writes, EAT keymap
  integration;
- public commands and shutdown/wrap-up hooks:
  =cj/ai-term=, =cj/ai-term-pick-project=, =cj/ai-term-next=,
  =cj/ai-term-close=, =cj/ai-term-quit=, =cj/ai-term-live-count=,
  =cj/ai-term-shutdown-countdown=.

The existing file has strong tests and comments, so this is not an emergency.
The structural risk is that future changes to tmux lifecycle, display geometry,
or project discovery all happen in the same large file and can accidentally
couple to each other.

Fix shape:
- Keep =ai-term.el= as the public API, user options, keymap, and compatibility
  require point.
- Extract project/session helpers to =ai-term-sessions.el=:
  candidate discovery, tmux names, live tmux parsing, launch-command building,
  active-agent-dir rotation inputs.
- Extract display/window policy to =ai-term-display.el=:
  display-buffer action functions, toggle capture/restore state, working-buffer
  swap, display rule list.
- Extract EAT/tmux buffer backend to =ai-term-backend-eat.el=:
  create/reattach buffer, pty send helper, EAT keymap integration. Keep the name
  backend-specific so a future backend swap is localized.
- Keep shutdown/wrap-up commands either in =ai-term.el= or a small
  =ai-term-shutdown.el= if they continue to grow.

Acceptance checks:
- Existing =test-ai-term-*.el= coverage remains green.
- Session/project tests can require the session module without loading EAT.
- Display tests can stub session/backend functions and exercise only window
  behavior.
- The public =C-; a= commands and =M-SPC= binding continue to resolve exactly
  as before.

*** TODO [#B] Define and apply a module layout convention for pure helpers, state/process code, commands, and keymaps :refactor:
Locations: recurring pattern across modules; representative examples:
=modules/custom-ordering.el=, =modules/custom-text-enclose.el=,
=modules/calendar-sync.el=, =modules/video-audio-recording.el=,
=modules/ai-term.el=, =modules/org-webclipper.el=.

Issue: The config has a good recurring pattern in several small command modules:
pure helpers first, thin interactive wrappers next, keymap/footer last.
=custom-ordering.el= is a good example: internal transform helpers like
=cj/--arrayify= and =cj/--unarrayify= are separate from commands like
=cj/arrayify=, and the keymap sits at the bottom.

The pattern is not explicit, and larger modules drift:
- some public commands are interleaved with low-level helpers;
- process/network/shell functions sit beside parser functions;
- keymap/footer blocks vary in naming and location;
- lazy =require= forms sometimes appear mid-file without a clear convention;
- state variables, defcustoms, and implementation constants are not always
  grouped the same way.

Fix shape:
- Write a short local convention, probably in =docs/design/module-structure.org=
  or a section of an existing architecture spec. Recommended order:
  1. package header, Commentary, Code;
  2. hard =require= forms and declarations;
  3. defgroup/defcustom/defface;
  4. internal state variables;
  5. pure helpers with no buffer/process/UI side effects;
  6. state/process/IO helpers;
  7. interactive commands;
  8. keymap registration and which-key labels;
  9. provide footer.
- Document exceptions: package =use-package= blocks may sit near the commands
  they configure if that is clearer; lazy =require= belongs at the call site
  only when it avoids a real startup dependency and has a comment naming why.
- Apply the convention opportunistically to 2-3 representative modules first:
  one small pure command module, one medium integration module, and one large
  process module.

Acceptance checks:
- The convention document names real examples from this repository.
- At least one module refactor lands with no behavior changes and only focused
  tests/byte-compile verification.
- Future module reviews can cite the convention instead of re-arguing layout.

*** TODO [#B] Normalize Elisp package structure conventions across owned and generated files :refactor:test:
Locations found during the 2026-06-28 pass:
- =modules/auth-config.el:1= starts with =;; auth-config.el ---= instead of a
  package header beginning with =;;;=.
- =modules/dwim-shell-config.el:1= starts with =;; dwim-shell-config.el ---=.
- =modules/local-repository.el:1= has a BOM before the =;;;= header.
- =custom/c-boxes.el:1= has no normal package header, Commentary marker, Code
  marker, or provide footer.
- =calendar-sync.local.el:1= has a package header/footer shape but no
  =;;; Commentary:= or =;;; Code:= markers.
- =browser-choice.el:1= is generated with =;;; Browser choice - Auto-generated=
  and no lexical-binding/canonical package header.

Issue: The load-graph header contract in =todo.org= covers the custom module
metadata block, but it does not cover normal Elisp package conventions. These
files still break tooling expectations for package headers, generated-file
headers, Commentary/Code markers, and sometimes byte-compile/checkdoc scans.

Fix shape:
- Add a lightweight convention/test that checks repository-owned active Elisp
  files for:
  - first line matching =;;; NAME.el --- SUMMARY -*- ... -*-=, unless explicitly
    exempted as vendored/generated/private;
  - =;;; Commentary:= before =;;; Code:=;
  - =provide= footer where the file is require-able;
  - no BOM before the package header.
- Fix owned files directly:
  - =auth-config.el= and =dwim-shell-config.el=: change first line to =;;;=.
  - =local-repository.el=: remove the BOM and keep a normal header.
  - =calendar-sync.local.el=: add Commentary/Code markers or explicitly exempt
    private local config from package checks.
- Fix generators for generated files:
  - =modules/browser-config.el= should generate a proper header for
    =browser-choice.el=, e.g.
    =;;; browser-choice.el --- Generated browser selection -*- lexical-binding: t; -*-=.
  - =scripts/theme-studio/build-theme.el= should continue to generate a proper
    header for theme files and should be included/exempted by policy.
- Decide whether =custom/c-boxes.el= is owned enough to normalize or vendored
  enough to exempt.

Acceptance checks:
- New or updated structural test fails on the malformed files before the fix.
- The test has a short, explicit exemption list for true vendor/generated/private
  files.
- =make test= or the relevant architecture/header test passes after fixes.

*** TODO [#C] Split or rehome the unrelated commands in custom-misc.el :refactor:
Location: =modules/custom-misc.el=.

Issue: =custom-misc.el= is named as a miscellaneous bucket and currently holds
unrelated behavior:
- delimiter navigation: =cj/jump-to-matching-paren=;
- buffer/region formatting: =cj/--format-region= and =cj/format-region-or-buffer=;
- previous-buffer toggle: =cj/switch-to-previous-buffer=;
- word/character counts: =cj/--count-words=, =cj/count-words-buffer-or-region=,
  =cj/--count-characters=, =cj/count-characters-buffer-or-region=;
- fraction glyph conversion: =cj/--replace-fraction-glyphs=,
  =cj/replace-fraction-glyphs=;
- global =align-regexp= advice: =cj/align-regexp-with-spaces=.

Each function is small, but the module has no coherent ownership rule beyond
"small things that did not fit elsewhere." That makes future additions likely
to land here by default, and it hides the fact that some pieces have better
homes already.

Fix shape:
- Rehome formatting to a shared formatting helper/module if it overlaps with
  =cj/format-region-with-program= or language format commands; otherwise keep
  a small =custom-format.el=.
- Move counts to a =custom-counts.el= or into a text/prose utility module.
- Move delimiter jump to a navigation/editing module, possibly
  =custom-line-paragraph.el= or a new =custom-navigation.el= depending on
  desired keymap ownership.
- Move fraction glyph conversion to a text transform module, likely
  =custom-case.el= or a new =custom-text-transform.el=.
- Keep a compatibility shim in =custom-misc.el= temporarily if external callers
  exist, but stop adding new commands there.

Acceptance checks:
- Search for all =cj/= symbols moved from =custom-misc.el= and update callers,
  tests, and keymap registrations.
- Existing =test-custom-misc-*.el= tests either move with their functions or
  become compatibility tests.
- =custom-misc.el= is deleted or reduced to a short compatibility module with a
  sunset note.

*** TODO [#C] Define a policy for vendor, archive, generated, and private Elisp files :refactor:
Locations affected:
- vendored/local third-party files under =custom/=, e.g. =custom/c-boxes.el=,
  =custom/elpa-mirror.el=, =custom/edit-indirect.el=, =custom/titlecase.el=,
  =custom/titlecase-data.el=, =custom/eplot.el=;
- archived GPTel code under =archive/gptel/=;
- generated files such as =themes/WIP-theme.el= and =browser-choice.el=;
- private local config such as =calendar-sync.local.el=.

Issue: Structural and documentation audits currently treat all Elisp files as
one population unless the reviewer manually remembers which files are owned,
vendored, archived, generated, or private. That produces noisy findings and
unclear expectations:
- Should vendored files be normalized to house package/comment conventions, or
  kept close to upstream?
- Should archived code be fixed, exempted, or ignored unless restored?
- Should generated files be fixed in the generated output or in the generator?
- Should private local config follow package conventions or a smaller template?

Fix shape:
- Add a policy document or a small section in the architecture docs that defines
  file classes:
  - Owned active config: must follow module/package/header/test conventions.
  - Vendored code: prefer upstream shape; local changes should be minimal and
    documented.
  - Archived code: excluded from active architecture checks unless the task is
    explicitly about archive cleanup.
  - Generated code: source of truth is the generator/input; fix generator output,
    not hand-edited generated files.
  - Private local config: must avoid secrets and should have a minimal readable
    header, but may be exempt from require/provide expectations.
- Add or update architecture/header tests to consume that classification rather
  than relying on ad hoc file globs.
- Put the classification in a machine-readable place if practical, e.g. a plist
  in the test file, an Org table in =docs/design/module-inventory.org=, or a
  small =docs/design/file-classes.org= that tests can parse later.

Acceptance checks:
- A reviewer can tell whether =custom/titlecase.el=, =archive/gptel/modules/*=,
  =themes/WIP-theme.el=, =browser-choice.el=, and =calendar-sync.local.el= are
  in or out of active structural checks without guessing.
- At least one architecture/header test uses the policy or exemption list.
- Generated-file fixes happen in the generator where applicable.

*** TODO [#C] Audit public/private naming boundaries across config-owned Elisp :refactor:
Locations and examples:
- =modules/local-repository.el= defines unprefixed =car-member= and
  =localrepo-initialize=.
- =modules/external-open.el= defines =default-open-extensions= without a
  =cj/= or package prefix.
- Package-private helpers vary between =cj/--name= and package-specific
  =calendar-sync--name= / =mouse-trap--name= styles.
- Some modules expose public command names where a private helper would be safer,
  while others use =cj/--= for helpers that are tested across files.

Issue: Naming mostly works in practice, but the boundary is not explicit. In a
large personal config loaded into one Emacs namespace, unprefixed symbols and
unclear private/public boundaries increase collision risk and make ownership
harder to infer. The =local-repository.el= case is already partly logged as a
module-specific cleanup in =todo.org=, but the broader convention is not.

Fix shape:
- Write a short naming convention:
  - user-facing commands and shared helpers use =cj/...=;
  - private helpers inside =cj=-owned modules use =cj/--...= unless the module
    is intentionally package-like;
  - package-like standalone modules use =package--...= for internals and
    =package-...= for public API;
  - no new unprefixed defvars/defuns in owned config modules;
  - tested private helpers may remain private, but test files should make that
    intentional rather than treating them as public API.
- Run a mechanical scan for owned files:
  =rg -n "^\\((defun|defvar|defcustom|defconst|defgroup) [^ )/]+\\b" modules custom=,
  excluding true package/vendor files by the file-class policy above.
- Rename only clear low-risk cases first, with compatibility aliases where
  external callers may exist.

Acceptance checks:
- The scan produces either no unexpected unprefixed symbols or a documented
  allowlist.
- Renames are covered by focused tests or alias tests.
- The convention is referenced by future module review tasks.

* Emacs Someday/Maybe

** TODO [#D] GPTel orphan tasks and useful ideas :feature:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-01
:END:

On 2026-06-23 gptel was archived out of the live config (its modules,
tools, tests, and specs moved to archive/gptel/) because it sees little
use.  This subtree was the gptel agentic-tool feature backlog.  I kept it
here in Someday/Maybe instead of deleting it: most of the child ideas
below are agent-tool concepts that are not gptel-specific (org-roam node
tools, git section tools, ripgrep / pandoc / ffmpeg / jq wrappers,
messaging and buffer-state tools) and would carry over to the ai-term
Claude agents or an MCP tool layer if that path is taken.  They are
reference, not active work.

Categories below thematize the agent affordances the design doc
[[file:docs/design/gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]]
points at -- Git, Org, messaging, file / buffer / workspace state,
media, and the dev loop.  The shortlist's first-batch ADOPT tools
(git_status / git_log / git_diff / web_fetch) already shipped; the
themes below are next-tier work where the agent treats Emacs as a
structured workspace, not a text terminal.  Per-theme spec lives in
the task body once written; implementation tasks land as siblings
of the spec heading once the spec is approved.  The magit-backend
reimplementation of the shipped git tools is tracked separately in
[[id:bd47c9a8-aae1-4a3d-ad5b-b8767f2fd580][gptel-git-tools-magit-backend-spec.org]].

*** TODO [#C] Wire Up MCP.el so That GPTel Has Access to MCP Servers via GPTel Tools

**** 2026-05-16 Sat @ 15:44:36 -0500 Spec

Design doc: [[id:b4c274c5-8572-4a7b-b657-d315712bd6af][docs/specs/mcp-el-gptel-integration-spec-doing.org]]

**** 2026-05-17 Sun @ 14:14:34 -0500 Landed ai-mcp.el pure-helper foundation

Commit =54d231be=.  Sections 1 (constants + defcustoms) and 3 (pure helpers) of the seven-section outline.  41 ERT tests, all green.  Refactor audit caught two duplications during Phase 4 and folded them into the same commit (=cj/mcp--get-server-entry= and =cj/mcp--name-matches-p=).  Phase 1.5 (confirmation contract) is next.

**** TODO [#C] Phase 1.5 -- GPTel confirmation contract

*Goal:* flip =gptel-confirm-tool-calls= to ='auto= and gate the existing local tools that need it.

*Entry:* Phase 1 module exists and helpers tested.

*DECISION (cj):* which of the existing local tools register with =:confirm t= once ='auto= is in effect?  Reads (=read_buffer=, =read_text_file=, =list_directory_files=, =git_status=, =git_log=, =git_diff=) clearly stay =:confirm nil=.  Judgment calls:
- =web_fetch= -- fetches arbitrary URLs the agent supplies.  Spec recommends gating.
- =write_text_file= -- writes any path under =$HOME= with agent-supplied content.
- =update_text_file= -- modifies an existing file with an agent-supplied transform.
- =move_to_trash= -- moves a path to trash (reversible but disruptive).

*Deliverables:*
- =ai-mcp.el= setup section runs =(setq gptel-confirm-tool-calls 'auto)=.
- Remove =(setq gptel-confirm-tool-calls nil)= from =modules/ai-config.el:386= with a comment pointing at =ai-mcp.el=.
- For each tool the decision marks "gate," add =:confirm t= to its =gptel-make-tool= form.
- Tests in =tests/test-ai-mcp-confirm-contract.el= asserting: =gptel-confirm-tool-calls= is ='auto= after load; write-classified stub MCP tool with =:confirm t= triggers the confirm branch in =gptel-send='s dispatch (stub the prompt); read-classified MCP tool with =:confirm nil= does not; =git_log= (=:confirm nil=) still runs without prompting; each newly-gated local tool does prompt.

*Exit:* tests green.  Manual smoke: open GPTel, call a gated tool, confirm prompt appears.  Call =git_log=, no prompt.

**** TODO [#B] Phase 2 -- Compat layer + registration pipeline (fake inventory)

*Goal:* implement the mcp.el compat wrappers and the tool-registration pipeline against stubbed =mcp-server-connections=.

*Entry:* Phase 1.5 proves gptel respects per-tool =:confirm= slot.

*Deliverables:*
- Section 4 of =ai-mcp.el= (compat layer): =cj/mcp--server-status=, =cj/mcp--server-tools=, =cj/mcp--server-name=, =cj/mcp--assert-capabilities=.  Each helper documents the upstream commit / file location it targets.
- Section 5 of =ai-mcp.el= (registration pipeline): =cj/mcp--register-tool=, =cj/mcp--register-server-tools=, =cj/mcp--deregister-server-tools=, =cj/mcp--rewrite-plist=, =cj/mcp--registered-tools= hash.
- All MCP tools register with =:async t=.
- Tests in =tests/test-ai-mcp-registration.el=.

*Exit:* with a stubbed =mcp-server-connections=, registration produces correctly prefixed =mcp__SERVER__TOOL= entries in =gptel-tools=; closures call =mcp-call-tool SERVER REMOTE-NAME= (verified by stubbing =mcp-async-call-tool=); deregistration removes only MCP-owned tools and leaves a pre-populated local =git_log= entry intact; re-registration replaces function pointer without duplicating menu entries; confirm overrides win over patterns.

**** TODO [#B] Phase 3 -- Async state machine + timer-race timeout wrapper

*Goal:* implement the lifecycle state machine and the per-call timer-race timeout.

*Entry:* Phase 2 registration works against stubs.

*Deliverables:*
- Section 6 of =ai-mcp.el= (async state machine): =cj/mcp--state=, =cj/mcp--server-status= alist, =cj/mcp--stall-timer=, =cj/mcp-ensure-started=, =cj/mcp--on-hub-callback=, =cj/mcp--poll-status=, =cj/mcp--start-stall-timer=, =cj/mcp--build-status-from-specs=.
- =cj/mcp--wrap-async-with-timeout= (timer/callback race; both branches set =done= before invoking gptel callback so late responses are ignored).
- Tests in =tests/test-ai-mcp-async.el=.

*Exit:* =cj/mcp-ensure-started= returns in <100 ms with delayed-callback stubs; stall timer fires for stuck servers; timer-race wrapper handles all three orderings (MCP-first, timer-first, late-MCP-after-timer); async error path (=:error-callback= without inited callback) reaches =failed= state via polling.

**** TODO [#B] Phase 4 -- First real connection (drawio or slack-deepsat)

*Goal:* wire one real no-auth server end-to-end against actual mcp.el and prove the stubbed Phase 3 behavior matches reality.

*Entry:* Phase 3 async works against stubs.

*Deliverables:*
- Add =use-package mcp= to =ai-mcp.el= (MELPA active, =:load-path= for local checkout commented).
- =cj/mcp--assert-capabilities= called at load time; signals clearly if mcp.el is too old.
- Set =cj/mcp-enabled-servers= temporarily to =("drawio")= (or =("slack-deepsat")= if the local proxy is running).
- First real =cj/mcp-ensure-started= invocation from =cj/toggle-gptel=.

*Exit:* manual smoke -- =C-; a t= opens GPTel without blocking; within 30 s, drawio (or slack-deepsat) tools appear in =gptel-menu= grouped by category; calling a tool returns expected output; killing the subprocess externally surfaces as =failed= in =cj/mcp--server-status=.

**** TODO [#B] Phase 5 -- Status UX + commands + doctor (static)

*Goal:* ship the full server-management UX so partial-availability and failures are visible.

*Entry:* Phase 4 proves a real connection works.

*Deliverables:*
- Section 7 of =ai-mcp.el= (UI).
- Commands: =cj/mcp-status= (echo-area summary keyed off =cj/mcp--state=), =cj/mcp-list-tools= (tabulated buffer with failed servers at top in red face; keys =g r c RET q=), =cj/mcp-doctor= (static mode only -- capability, =npx=/=uvx=, Claude config, per-server env, local endpoints; output buffer keys =c r q=), =cj/mcp-wait-until-ready=, =cj/mcp-hub= (thin wrapper that ensures startup first), =cj/mcp-restart-failed=, =cj/mcp-restart-server=, =cj/mcp-stop-all=.
- Keymap: =C-; a C= subprefix bound in =ai-config.el='s autoload section.  Keys =h s l r R S d w=.
- which-key labels for every binding.
- =kill-emacs-hook= registration for =cj/mcp-stop-all=.
- Investigation: does =gptel-menu= refresh after mid-call tool registration?  Document the answer in =ai-mcp.el= commentary; if it requires close+reopen, add to known UX caveats.

*Exit:* all keymap bindings work; audit buffer surfaces failed servers prominently; doctor identifies each scenario in the manual test matrix; status command shows the right state for each phase transition.

**** TODO [#B] Phase 6 -- HTTP servers (linear, notion)

*Goal:* add the two HTTP-transport servers with in-protocol OAuth.

*Entry:* Phase 5 UX shipped.

*Deliverables:*
- Add =linear= and =notion= back to =cj/mcp-enabled-servers=.
- Doctor gains live-auth-check mode (=C-u C-; a C d=): invokes a single safe read per auth class to verify OAuth tokens haven't silently expired.  Static checks first; live probe only fires after static passes.
- OAuth recovery pattern matcher surfaces auth URLs in =cj/mcp-status= on first connect.

*Exit:* first connect surfaces the OAuth URL through the recovery pattern; after browser handshake completes, subsequent connects succeed without prompt; live-auth-check correctly identifies a deliberately revoked token; both servers appear ready in the audit buffer.

**** TODO [#B] Phase 7 -- Env-dependent stdio servers (figma, google-*)

*Goal:* add the remaining five env-dependent servers.

*Entry:* Phase 6 HTTP servers connect cleanly.

*Deliverables:*
- Add =figma=, =google-calendar=, =google-docs-personal=, =google-docs-work=, =google-keep= to =cj/mcp-enabled-servers=.
- Verify env-merge from =~/.claude.json= for each (the mtime-cached reader from Phase 1).
- Verify figma's =:secret-args= splicing places the API key correctly without echoing it.
- Manual smoke: simulate token expiry on one Google server; recovery message points at "re-auth via Claude Code, then C-; a C r SERVER".

*Exit:* all 9 servers reach =ready= state on a clean machine.  Sentinel-grep check across status / audit / hub / errors / audit-log shows zero secret leakage.  Doctor's live-auth covers each auth class (oauth, token, args-token, in-protocol, local, none).

**** TODO [#B] Phase 8 -- Privacy + audit polish

*Goal:* land the final UX polish and documentation.

*Entry:* all 9 servers working.

*Deliverables:*
- Audit buffer privacy header: "Tool results land in =gptel-tools= responses; saved conversations persist them.  Use =cj/gptel-autosave-toggle= per buffer to opt out."
- =cj/mcp-tool-audit-log-enabled= defcustom + log writer (=~/.emacs.d/data/mcp-tool-log/YYYY-MM-DD.log= -- metadata only, one line per call, daily rotation).
- =ai-mcp.el= commentary updated with the code-organization outline as a table of contents.
- Final pass on tests covering saved-conversation behavior (autosave persists MCP tool results; toggling off prevents persistence).

*Exit:* all 10 acceptance criteria from the spec pass.  Manual matrix run end-to-end on a fresh Emacs.  Working tree clean.

*** TODO [#C] Wrap the gh CLI as a GPTel tool

**** 2026-05-16 Sat @ 16:20:00 -0500 Spec

Design doc: [[id:a124dd0f-1f40-4533-aeb8-595d93e20865][docs/specs/gptel-gh-tool-spec.org]]

*** TODO [#C] GPTel should autosave regularly after a conversation is saved
*** TODO [#B] Org Workflow Related Tools

Affordances that expose the Org workspace -- agenda state, capture
targets, org-roam nodes and backlinks, dailies, drill review state --
to the agent as structured context, not raw .org buffer text.

**** TODO [#B] Agenda state tools :feature:

Read scheduled / deadline / waiting tasks for a date range; query by
tag, priority, or TODO keyword; list what's blocking today.  Lets the
agent answer "what's on the critical path this week" without me
pasting agenda output, and feeds the daily-prep / wrap-up workflows.

**** TODO [#B] Org-roam node tools :feature:

Resolve a topic to its node; return body + backlinks; list nodes by
tag; surface dailies for a date range.  Lets the agent reason over
the personal knowledge graph and write back into it via the capture
tools below.

**** TODO [#B] Capture creation tools :feature:

Drive =org-capture= from a template key + body string.  Lets the
agent file inbox items, reading notes, journal entries, or roam
nodes without me leaving the chat.  Tight pairing with the
=cj/org-capture= optimization task in todo.org.

**** TODO [#B] Org-drill review tools :feature:

Surface next-due drill cards in =drill-dir=; let the agent quiz on a
topic and report performance.  Useful for prompted recall sessions
("ask me five medical-Spanish cards") and for "did this card stick"
analysis.

*** TODO [#B] Git Related Tools

Affordances that expose magit's structured view of a repo -- sections,
staged-vs-unstaged, commit metadata, rebase / conflict state -- as
first-class tools rather than asking the model to reason over raw
diff text.

**** TODO [#B] Section-aware git tools :feature:

Expose Magit sections as first-class GPTel tools: current section type,
heading, file, hunk range, and content; sibling sections under the same
file; staged / unstaged / untracked status; commit metadata around the
selected commit or branch; the exact staged patch that would be
committed.  Lets prompts say "review the file section at point" or
"explain this hunk in the context of adjacent hunks" without manual
context-copying.

**** TODO [#B] Commit intent workbench :feature:

Transient that builds a commit intentionally:
1. Agent reads unstaged + staged changes.
2. Agent proposes coherent commit groups.
3. User selects groups in a Magit-style buffer.
4. Agent stages those paths or hunks only after confirmation.
5. Agent generates a message reflecting the selected intent.

Addresses the common case of two or three unrelated edits in one
working tree -- a single commit-message generator can't handle that
cleanly.

**** TODO [#B] Patch narrative buffer :feature:

Generate an Org buffer that explains a change set as a reviewable
narrative:
- "What changed" by subsystem.
- "Why it appears to have changed" inferred from names, tests, and docs.
- "Risk areas" with links back to Magit file sections.
- "Suggested verification" using local Makefile targets when present.

Reusable artifact: paste into a PR description, save with an AI
session, or file into org-roam.

**** TODO [#B] Review-thread simulator :feature:

Before opening a PR, create a local review buffer with inline comments
attached to Magit diff positions.  The agent writes comments as if
reviewing someone else's patch:
- Comments grouped by severity.
- Each comment links to file and line.
- Resolved comments check off in Org.
- Accepted suggestions apply through the existing text-update tools.

Makes "review my diff" less ephemeral and avoids losing useful findings
inside a chat transcript.

**** TODO [#B] Rebase and conflict coach :feature:

When Magit enters a rebase, cherry-pick, merge, or conflict state,
expose an agent command that reads:
- Git operation state from =.git/=.
- Conflict markers in the worktree.
- Relevant commits from =git log --merge= or the rebase todo.
- The current Magit status sections.

The agent explains the conflict in domain terms and proposes a
resolution patch; the actual edit and =git add= stay under explicit
user control.

**** TODO [#B] Regression archaeology :feature:

Magit transient that runs a bisect-like reasoning workflow:
- Ask for a symptom and a known-good / known-bad range.
- Summarize candidate commits in small batches.
- Use tests or user-provided repro commands when available.
- Maintain a bisect journal in an Org buffer.

Even when the agent can't run the whole bisect, it keeps the
investigation structured and preserves why each commit was judged
good or bad.

**** TODO [#B] Messaging Related Tools

Affordances over mu4e, Slack, Telegram, and ERC.  Same shape across
protocols: read recent threads, search by sender / topic, compose a
draft from a prompt + thread context, leave the send under explicit
user control.

***** TODO [#B] Mu4e thread and compose tools :feature:

Read the message at point and surrounding thread (with attachments
summarized); query the inbox by =from:= / =subject:= / date range;
compose a draft from a prompt + thread context using =org-msg=.
Pairs with the existing =mu4e-org-contacts-integration.el=.

***** TODO [#B] Slack thread and compose tools :feature:

Read channel / DM / thread history through =emacs-slack=; search by
user or channel; compose a draft message but leave sending to me.
Mirrors the mu4e shape so the agent's interface is uniform across
messaging protocols.

***** TODO [#B] Telegram and IRC read tools :feature:

Same shape as Slack for =telega= (Telegram) and =erc= (IRC):
recent-message reads, search, and draft compose.  Bundled because
the API shape is identical even if the underlying clients differ.

***** TODO [#B] Contact resolution tools :feature:

Resolve a name to email / Slack ID / Telegram handle via
=org-contacts= and the configured address books.  Removes the
"who's this person again" friction from the compose flows above.

**** TODO [#B] File and Buffer Related Tools

Affordances that expose the user's actual workspace -- open buffers,
narrowed regions, marked files, vterm / eshell sessions -- as
structured context.  Stops the model from asking "what file are you
looking at" or "what region is selected."

***** TODO [#B] Buffer state tools :feature:

List visible buffers with major-mode + file (when any); read the
narrowed region instead of the whole buffer; report point + mark
positions and the active region's text.  The single most-asked
question between turns becomes a tool call.

***** TODO [#B] Dirvish / Dired tools :feature:

Read marked files, sort state, and filter state from a Dired or
Dirvish buffer.  Lets the agent operate on "the files I just marked"
rather than "files in this directory" -- a real distinction in any
review or refactor workflow.

***** TODO [#B] Vterm session tools :feature:

Recent command output from a named vterm session; scroll-history
search.  Pairs naturally with the =ai-vterm= design: the agent
running in one project's vterm can read another project's vterm
without leaving the chat.

***** TODO [#B] Eshell session tools :feature:

Same shape as the vterm tools for =eshell= sessions -- last-command
output, history search, current directory.  Most useful for
agent-driven inspection of long-running pipelines.

**** TODO [#B] Filesystem Related Tools

Affordances that let the agent operate on actual files on disk and
run common CLI utilities -- pandoc, ffmpeg, imagemagick, ripgrep,
fd, jq -- rather than relying on me to paste content or run
commands by hand.

*Design tension to resolve before any of these ship: one tool per
utility, or one generic =run_shell_command=?*

The shortlist's first pass DEFERRED a generic =run_shell_command=:
sandboxing to HOME + /tmp with a denylist for destructive ops is
straightforward, but the denylist can never be exhaustive, and
"confirmation for everything else" becomes click-fatigue.

The children below take the other path -- *one gptel tool per
binary*, with a strictly-typed argv shape (e.g.
=pandoc_convert(input_path, output_format)=, not
=pandoc_convert(args_string)=).  Each tool:

- Validates its own paths (must be under HOME, outputs in a
  sandboxed dir).
- Rejects dangerous flags explicitly (pandoc =--filter=, ffmpeg's
  =-protocol_whitelist= chicanery, imagemagick's policy bypasses).
- Runs via =call-process= with an argv list -- no shell parsing,
  no string-interpolation injection.
- Caps output and reports truncation inline.

The trade-off is breadth: every new CLI tool means a new gptel tool
file.  Acceptable because (a) the list of utilities I actually need
agent access to is small (~8 below covers most of it), and (b) each
wrapper gets type-checked argv and a focused description the model
can reason over, which is genuinely better than a free-form
=run_shell_command(string)=.

The =eshell_submit= entry at the end is the escape hatch for one-
off needs the wrappers don't cover -- =:confirm t= always.

Adjacent categories: the existing =gptel-tools/= file CRUD
(=read_text_file=, =write_text_file=, =update_text_file=,
=list_directory_files=, =move_to_trash=) is the foundation this
category extends.  =web_fetch= is the network-fetch counterpart.

***** TODO [#B] Document conversion (pandoc) :feature:

Convert between markdown, org, html, pdf, docx, latex, epub, plain
text.  Most common use: "extract this docx to markdown so I can
read it inline."  Strict argv: input path, output format, optional
output path.  Reject =--filter= and =--lua-filter= (arbitrary code
execution).  Output written to a sandbox dir unless explicit
override.

***** TODO [#B] Image manipulation (imagemagick) :feature:

Resize, format-convert, get-metadata (=identify=), optionally crop /
rotate / annotate.  Common use: "resize this PNG to a thumbnail" or
"convert these HEICs to JPEGs."  Strict argv per operation.
Reject pre-validated dangerous formats (the historical EXR / SVG /
MVG CVE surface) unless explicitly enabled.  ImageMagick's
=policy.xml= is the underlying defense; the wrapper enforces it at
the tool boundary too.

***** TODO [#B] Audio / video processing (ffmpeg) :feature:

Trim, transcode, extract audio, get-metadata (=ffprobe=).  Paths
under HOME only; reject network-protocol inputs (=http:= / =rtmp:=
/ =rtsp:=) so the model can't pull from arbitrary sources.  Pairs
with the existing transcription module -- the same "extract audio
from video" path =cj/transcribe-media= uses internally.

***** TODO [#B] Content search (ripgrep) :feature:

=rg= wrapper with path / glob filtering, result-count cap, optional
literal-vs-regex mode.  Pure read.  Was in the shortlist's ADOPT
bucket as =search_in_files=.  Highest-leverage filesystem tool by
expected call frequency -- "where in this repo is X" is the
question I paste agent output for most often.

***** TODO [#B] File discovery (fd) :feature:

=fd= (or =find= fallback) wrapper, capped result count.  Pure
read, lower stakes than =search_in_files= (filenames only, no
content).  Common pairing: =find_file_by_name= then
=read_text_file=.

***** TODO [#B] Metadata extraction (file / exiftool) :feature:

=file= for MIME-type detection; =exiftool= for image / video /
audio metadata.  Lets the agent answer "what is this file" or
"when was this photo taken" without me opening external tools.
Pure read.

***** TODO [#B] Structured data processing (jq / yq) :feature:

=jq= for JSON, =yq= for YAML / TOML.  Filter / project / transform
structured data into a smaller, more focused view before reading.
Strictly read-only -- output goes to the chat, not to disk.  The
agent often wants "the third element of .results" from a JSON file
and this is much cheaper than pasting the whole thing.

***** TODO [#B] Eshell command submission :feature:

Submit a single eshell command line, return output (capped).
=:confirm t= always -- this is the escape hatch where the
strictly-typed wrappers above don't fit, so each invocation needs
my eyeball.  Eshell parses in-process (no /bin/sh fork) so the
security surface is narrower than a shell command runner, but it's
still effectively arbitrary execution -- treat it as such.

**** TODO [#B] Media and Reading Related Tools

Affordances over non-code content: feeds, PDFs, EPUBs, music.  The
agent's job here is summarize / extract / queue, not produce.

***** TODO [#B] Elfeed entry tools :feature:

Read entry body; list unread by feed or tag; mark read after a
summary lands in a roam node or inbox.  Enables "give me the
non-noise headlines from this week's feeds" flows.

***** TODO [#B] PDF and EPUB text tools :feature:

Extract plain text from a PDF page or page range (via =pdftotext=)
and from an EPUB (via the existing nov-mode pipeline).  Lets the
agent summarize / quote a research paper or book chapter without
me pasting passages.

***** TODO [#B] EMMS playback and queue tools :feature:

Current track, queue contents, playback state; queue or play a
path; compose a playlist from a prompt ("play something focusing
that's not Nick Cave").  Light tools, but a frequent friction
point.

**** TODO [#B] Development Workflow Related Tools

Affordances over the dev loop: compilation output, test invocation,
coverage / profile data, flycheck / flymake diagnostics.

***** TODO [#B] Compilation buffer tools :feature:

Read the most recent =compile= buffer output; parse error locations
to =file:line=; summarize what broke.  Pairs with the F6 test-runner
flow -- "tell me what's failing" becomes a single agent turn
instead of paste + parse.

***** TODO [#B] Project test invocation tools :feature:

Run =make test-file FILE=X= / =make test-name TEST=Y= /
project-equivalent and return results.  Currently each agent guesses
the project convention; expose the canonical invocation explicitly
per project so the agent can run focused tests itself.

***** TODO [#B] Coverage and profile tools :feature:

Read the most recent SimpleCov JSON or profile dump.  Lets the
agent answer "what's still uncovered after this push" or "what
function dominates startup time" against real measured data.

***** TODO [#B] Diagnostic tools (flycheck / flymake) :feature:

Surface current-buffer or project-wide errors and warnings.  Useful
both as a "what's broken right now" check and as input to the
patch-narrative buffer / commit-intent workbench above.

**** CANCELLED [#B] gptel-magit activation fails on velox :bug:quick:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-01
:END:
Surfaced 2026-05-25 while diagnosing an unrelated load failure over SSH. velox-specific — the workstation has a current gptel and does not show it.

At startup (and reproducibly in batch) velox logs: "Unable to activate package `gptel-magit'. Required package `gptel-0.9.8' is unavailable." gptel-magit depends on gptel >= 0.9.8 and velox's installed gptel is older or missing, so it can't activate. A startup warning, not a blocker.

Reproduce:
: emacs --batch --no-site-file -L . -L modules --eval "(package-initialize)" --eval "(message \"done\")" 2>&1 | grep -i gptel

Next step: check the installed gptel version (=(assq 'gptel package-alist)= or =M-x package-list-packages=), update gptel to >= 0.9.8, then re-evaluate gptel-magit activation. If gptel was pinned/held on velox, reconcile the pin against the gptel-magit dependency.


** TODO [#C] Build an Org-native API workspace :feature:test:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:

Moved to Someday/Maybe on 2026-06-23 when gptel was archived.  This
design used gptel for its AI-assisted parts (restclient-ai.el, API
summaries, the AI-debugging ideas); with gptel archived those modules
are orphaned.  The non-AI parts (OpenAPI import, request execution,
response capture) still stand on their own, so I shelved the whole design
here rather than dropping it.  Pull it back to Open Work if the non-AI
core is worth building.

Build an Emacs-native API workspace layer that keeps =restclient.el= useful for
lightweight request execution while adding OpenAPI import, Org notebooks,
response capture, inline images, and =gptel=-assisted API documentation.

*** Spec

**** Summary
Build a small Emacs API-workspace layer that keeps =restclient.el= as the
plain-text request executor, while adding higher-level discovery, generation,
Org notebook, response handling, and =gptel=-assisted documentation workflows.

The intended result is not a Postman clone.  It should feel like an
Emacs-native API lab:
- generate request collections from OpenAPI/Swagger specs
- browse and execute requests from =.rest= files or Org notebooks
- save useful responses back into Org
- display image responses inline
- use =gptel= to explain APIs, endpoints, request bodies, and responses
- leave room for =verb.el= or Hurl where they are a better fit

**** Goals
- Preserve the current lightweight =restclient.el= workflow for ad-hoc calls.
- Add an OpenAPI importer that can generate useful first-draft request files.
- Add an Org workspace format for API notes, executable request blocks, results,
  response links, and generated summaries.
- Add response post-processing helpers for JSON, binary/image data, and model
  summaries.
- Make common auth flows easy to scaffold without storing secrets in generated
  files.
- Keep generated artifacts readable and editable by hand.
- Keep implementation modular enough that =verb.el= can be evaluated as a richer
  Org-native frontend.

**** Non-Goals
- Do not build a full graphical API client.
- Do not store secrets directly in Org or =.rest= files.
- Do not attempt complete OpenAPI 3.1 schema synthesis in the first pass.
- Do not require =gptel= for ordinary request execution.
- Do not make Hurl a runtime dependency for the restclient workflow.

**** Primary User Flows
***** Import An API
1. User runs =cj/restclient-import-openapi=.
2. Command prompts for a URL or local OpenAPI/Swagger file.
3. Command parses the spec into normalized endpoint records.
4. Command prompts for output format:
   - =restclient= request collection
   - Org API workspace
   - both
5. Command writes generated files under a project/API workspace directory.
6. Generated file includes host variables, auth placeholders, request examples,
   and a short summary of how to start using the collection.

***** Describe An API
1. User runs =cj/restclient-describe-api= from a generated workspace or spec file.
2. Command extracts API metadata, paths, operations, schemas, auth, and tags.
3. Command sends a bounded summary payload to =gptel=.
4. Result is inserted under an Org =Overview= subtree.

***** Execute And Capture A Request
1. User executes a request via =restclient.el= or =ob-restclient=.
2. Command captures response status, headers, content type, body, and timestamp
   when available.
3. JSON/XML responses can be inserted as source blocks or summarized.
4. Image responses are saved to an assets directory and linked inline in Org.
5. Binary responses that are not image-like are saved as file links.

***** Iterate On A Response
1. User runs helper commands against the last response:
   - pretty-print JSON/XML
   - run =jq=
   - summarize with =gptel=
   - extract a value into a restclient variable
   - save body to a file
2. The result is inserted near the endpoint subtree or shown in a temporary
   buffer depending on command prefix/options.

**** Proposed Modules
***** =modules/restclient-workspace.el=
Main configuration and user-facing commands.  Owns keybindings, workspace
creation, dispatch commands, and integration with existing restclient config.

***** =modules/restclient-openapi.el=
OpenAPI/Swagger loading and normalization:
- fetch URL or read file
- parse JSON/YAML where available
- normalize servers, paths, methods, parameters, request bodies, auth schemes,
  tags, operation IDs, and examples
- expose pure helper functions suitable for unit tests

***** =modules/restclient-generate.el=
Generation layer:
- render =.rest= / =.http= request collections
- render Org workspaces
- synthesize simple JSON request bodies from schemas/examples
- generate variables and auth placeholders

***** =modules/restclient-response.el=
Response helpers:
- identify content type
- save binary/image bodies
- insert Org links
- display inline images
- route JSON/XML/text handling
- track last response metadata

***** =modules/restclient-ai.el=
=gptel= integration:
- summarize API specs
- explain endpoint behavior
- generate example payload notes
- summarize responses
- keep prompts bounded and avoid sending secrets

**** File And Workspace Layout
Default generated workspace:

#+begin_src text
data/apis/<api-slug>/
  <api-slug>.rest
  <api-slug>.org
  openapi.json
  assets/
    responses/
#+end_src

The exact root should be configurable, defaulting to the existing REST data
directory if one is already present in the config.

**** Org Workspace Shape
#+begin_example
,* API Name
:PROPERTIES:
:OPENAPI_SOURCE: https://example.com/openapi.json
:BASE_URL: https://api.example.com
:END:

,** Overview
Generated or user-written API notes.

,** Auth
Token acquisition notes and placeholders.  No secrets stored here.

,** Endpoints
,*** GET /users
:PROPERTIES:
:OPERATION_ID: listUsers
:METHOD: GET
:PATH: /users
:END:

#+begin_src restclient :results raw
GET :host/users
Authorization: Bearer :token
Accept: application/json
#+end_src

,**** Notes
,**** Responses
#+end_example

**** Commands
- =cj/restclient-new-scratch= :: open a scratch =restclient-mode= buffer.
- =cj/restclient-open-file= :: open a REST file from the configured API data dir.
- =cj/restclient-import-openapi= :: generate a workspace from OpenAPI/Swagger.
- =cj/restclient-describe-api= :: insert a =gptel=-generated API overview.
- =cj/restclient-describe-endpoint= :: explain the endpoint at point.
- =cj/restclient-generate-example-body= :: generate or refresh sample JSON body.
- =cj/restclient-save-last-response= :: save response body and metadata.
- =cj/restclient-insert-last-response-org= :: insert response under Org subtree.
- =cj/restclient-display-image-response= :: save and display image response.
- =cj/restclient-response-jq= :: run =jq= against the last JSON response.
- =cj/restclient-copy-curl= :: copy the request at point as curl if supported.

**** Keybindings
Keep the existing prefix shape under =C-; R=:
- =C-; R n= :: new scratch request buffer
- =C-; R o= :: open REST file
- =C-; R i= :: import OpenAPI/Swagger
- =C-; R d= :: describe API or endpoint
- =C-; R s= :: save/capture last response
- =C-; R j= :: run =jq= on last response
- =C-; R m= :: transient menu for workspace commands

**** OpenAPI Import Details
Minimum first-pass support:
- OpenAPI 3.x JSON
- Swagger 2.0 JSON if easy to normalize
- YAML via available Emacs YAML library or external converter if already present
- =servers= / =host= + =basePath=
- path-level and operation-level parameters
- query/path/header parameters
- JSON request bodies
- examples and default schema values
- security schemes:
  - HTTP bearer
  - basic
  - API key header
  - API key query

First pass can skip or mark as unsupported:
- polymorphic schemas beyond simple =oneOf= / =anyOf= note generation
- multipart body generation
- full OAuth flows
- callbacks/webhooks
- complete response schema rendering

**** Secret Handling
- Generated files must use placeholders like =:token=, =:api-key=, or
  =:basic-auth=.
- Do not write tokens into generated files.
- Prefer variables loaded from auth-source, environment variables, or manually
  entered restclient variables.
- =gptel= prompts must strip obvious auth headers and secret-like values from
  request/response payloads before sending context.

**** Response Handling
- Text JSON/XML/HTML/plain responses may be inserted into Org as source blocks.
- JSON responses should support optional =jq= filters.
- Image responses should be saved under =assets/responses/= and inserted as Org
  file links.
- After inserting image links, call =org-display-inline-images= when in Org.
- Large responses should be saved as files and linked rather than inserted.
- Binary non-image responses should be saved and linked with content type notes.

**** Integration Choices To Evaluate
- =restclient.el= remains the default executor for =.rest= files.
- =ob-restclient= powers executable Org source blocks.
- =verb.el= should be evaluated as an alternate frontend for Org-native API
  workspaces because it already has tree inheritance, embedded Elisp, and image
  response display.
- Hurl should be evaluated as an export/test target, especially for chained
  request tests and CI assertions.

**** Testing Strategy
- Unit-test OpenAPI normalization with small fixture specs.
- Unit-test request generation for GET, POST, auth, query params, path params,
  and request-body examples.
- Unit-test secret redaction before =gptel= calls.
- Unit-test response classification and Org insertion helpers.
- Integration-test generated =.rest= files for representative APIs.
- Integration-test generated Org workspaces with =ob-restclient= where feasible.
- Avoid live network tests by default; use fixtures/stubs unless explicitly
  tagged =:network=.

**** First Milestone
1. Keep/verify existing restclient scratch/open commands.
2. Add a tiny OpenAPI JSON parser/normalizer for a fixture spec.
3. Generate a readable =.rest= collection with variables and examples.
4. Generate a matching Org workspace.
5. Add response save/link helpers for JSON and images.
6. Add a =gptel= API-summary command with secret redaction.
7. Add focused unit tests and one sample fixture.

**** Open Questions
- Should the canonical workspace be =.rest= first, Org first, or generated in
  both formats by default?
- Is =verb.el= a better primary target than =ob-restclient= for the Org notebook
  experience?
- Which YAML parser should be used if no YAML package is already configured?
- Where should API workspaces live by default: =data/=, =docs/=, or project root?
- Should response capture hook into restclient internals, or should capture be a
  separate explicit command operating on response buffers?
- How much schema synthesis is useful before it becomes noisy?

*** Ideas
- Treat =restclient.el= as the lightweight request scratchpad, and layer richer workflow commands around it instead of trying to turn it into Postman.
- Add an OpenAPI/Swagger importer:
  - prompt for a spec URL or local file
  - parse paths, methods, auth schemes, request bodies, and examples
  - generate a =.http= / =.rest= request collection
  - optionally generate an Org notebook with one subtree per endpoint
- Add an API description command using =gptel=:
  - summarize the API from an OpenAPI spec
  - explain each endpoint, auth requirement, parameters, and response shape
  - write the summary into the generated Org workspace
- Generate example requests automatically:
  - =GET= examples with query params
  - =POST= / =PUT= / =PATCH= examples with sample JSON bodies
  - =DELETE= examples with safe placeholder IDs
  - shared variables like =:host=, =:token=, =:api-version=, =:tenant=
- Add auth helpers:
  - bearer token insertion
  - basic auth
  - API key header/query param
  - OAuth token fetch request template
- Improve Org integration:
  - use =ob-restclient= for executable API notebooks
  - support =:jq= filters for clean JSON results
  - save response bodies under endpoint subtrees
  - capture request/response metadata as Org properties
- Handle images and binary responses:
  - detect image =Content-Type=
  - save response data into an assets directory
  - insert =[[file:...]]= links into Org
  - call =org-display-inline-images= after execution
- Add response-processing commands:
  - pretty-print JSON/XML
  - run =jq= against the last response
  - summarize response with =gptel=
  - extract fields into restclient variables for follow-up calls
- Add request collection ergonomics:
  - imenu/consult navigation by endpoint
  - transient menu for send/copy curl/jq/save response
  - templates for common headers
  - per-project API workspace discovery
- Investigate =verb.el= as the richer Org-native frontend:
  - Org tree inheritance for host/header/auth defaults
  - embedded Elisp in request specs
  - built-in display of image/PDF/SVG responses
  - likely better base for a notebook-style API client
- Investigate Hurl for repeatable API tests:
  - request chaining
  - captures
  - assertions
  - CI-friendly execution
  - possible export target from generated API workspaces

*** Original Goals
**** Keybindings to test
- C-; R n — new scratch *restclient* buffer (should open in restclient-mode)
- C-; R o — open .rest file (should default to data/ directory)

**** Functional tests
1. Open tutorial-api.rest, run JSONPlaceholder GET (C-c C-c) — verify response inline
2. Run POST example — verify 201 response with fake ID
3. Run httpbin header echo — verify custom headers echoed back
4. Navigate between requests with C-c C-n / C-c C-p
5. Test jq filtering (requires jq installed): restclient-jq loaded?
6. Open scratch buffer (C-; R n), type a request manually, execute
7. which-key shows "REST client" menu under C-; R
  
* Emacs Resolved
** TODO [#C] Color dashboard navigator independently of list items :feature:ux:
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
The dashboard navigator (icons + labels) and the recentf/project/bookmark list items are both painted by =dashboard-items-face=: the navigator gets a =dashboard-items-face= overlay, and overlays beat text properties, so the per-button =dashboard-navigator= face is inert. To color the navigator independently of the items, override where that overlay is applied — advise or redefine =dashboard-insert-navigator=, or strip/replace the overlay's face.
Triggered by: 2026-05-22 dashboard color work (L105).
** DONE [#B] C-<left>/<right>/<down> wrongly enter terminal copy-mode :bug:quick:
CLOSED: [2026-06-24 Wed]
Fixed 2026-06-24: per Craig, only C-<up> enters copy-mode now — all other arrows (C-<down>/<left>/<right> and the M-arrows) were dropped from both the ghostel-mode-map binding and ghostel-keymap-exceptions in modules/term-config.el, so C-<left>/C-<right> reach the shell as readline word-motion again. Also per Craig: C-<up> pressed while already in copy-mode just moves up — cj/term-copy-mode-up checks tmux pane_in_mode (and ghostel--input-mode without tmux) and skips re-entry, which would otherwise reset the cursor. 6 ERT tests rewritten; byte-compile clean; the live daemon was stripped of the stale bindings/exceptions and reloaded (C-<up> bound + an exception, C-<left> forwarded to the pty). Real-terminal scroll is the VERIFY under Manual testing and validation.
** DONE [#B] ai-term wrap-teardown + shutdown functions :feature:
CLOSED: [2026-06-24 Wed]
Done 2026-06-24: added the three headless functions to =modules/ai-term.el= per the rulesets contract — =cj/ai-term-quit= (kill aiv- session + agent buffer + restore layout, idempotent), =cj/ai-term-live-count= (integer gate), =cj/ai-term-shutdown-countdown= (gate re-check → abort-able run-at-time countdown → =cj/ai-term-shutdown-command=, a defcustom). Reused the existing kill/close helpers. 13 ERT tests (live-count parsing, quit kill+idempotency, gate-abort/cancel/tick); byte-compile + validate-modules + launch smoke clean; headless contracts verified live in the daemon (live-count→3, quit no-op returns the session name, countdown aborted with sessions live — no shutdown). The tmux/shutdown side effects and the both-sides end-to-end are a VERIFY under Manual testing and validation. Original task body:
The .emacs.d half of the rulesets wrap-it-up teardown / shutdown feature. Implement three functions in =modules/ai-term.el=, all callable headlessly via =emacsclient -e= (no interactive frame): =cj/ai-term-quit "<project>"= (teardown a project's aiv- tmux session + buffer + geometry restore), =cj/ai-term-live-count= (integer, the safety gate), =cj/ai-term-shutdown-countdown= (run-at-time timer). Craig's 2026-06-23 decisions: non-destructive qualifier = "with summary"/"and summarize"; countdown is a run-at-time timer (not a tty writer); safety gate uses cj/ai-term-live-count. Lands with the rulesets half (workflow + Stop hook already built/pushed). Spec: =inbox/PROCESSED-2026-06-23-2331-from-rulesets-ai-term-teardown-companion.org= (rulesets proposal: docs/design/2026-06-23-wrap-teardown-shutdown-proposal.org). Own focused session.
** DONE [#C] README holistic pass
CLOSED: [2026-06-24 Wed]
Holistic pass over README.org, changes approved by Craig: bumped the Emacs floor to 30 (developed on 30.2); corrected the module count (~100 → ~120); added docs/ to the layout and reworded scripts/ (now also theme-studio); added Theme Studio, the ghostel native terminal, and ai-term to Features; added make coverage-summary to the dev targets. From the roam inbox.
** DONE [#B] Theme-driven nerd-icons colors + filetype legend :feature:
CLOSED: [2026-06-24 Wed]
Dropped the runtime nerd-icons tint so icon color is theme-driven, and added a
theme-studio filetype-legend representation over the 34 =nerd-icons-*= color
faces. Spec:
[[file:docs/specs/theme-studio-nerd-icons-colors-spec.org][theme-studio-nerd-icons-colors-spec.org]].
Three Codex spec-review rounds (3 + 6 + 1 findings) incorporated; findings
[10/10], decisions [6/6]. Ready confirmed 2026-06-24 and implemented in a
no-approvals speedrun as the four dated phases below — full run-tests.sh and
=make test= green, all pushed. Live visual confirmation is a VERIFY under
Manual testing and validation. vNext follow-ups promoted to their own [#D] task.
*** 2026-06-24 Wed @ 05:54:34 -0400 Phase 1 — legend capture shipped
=scripts/theme-studio/build-nerd-icons-legend.el= resolves the 13 v1 rows from the live nerd-icons alists into =nerd-icons-legend.json= (committed); =generate.py='s =load_nerd_icons_legend= validates and falls back to the generic app on absent/malformed/empty/bad-row, with a warning. 7 Python tests. Committed (feat phase 1).
*** 2026-06-24 Wed @ 05:54:34 -0400 Phase 2 — bespoke legend preview shipped
nerd-icons registers as a bespoke app whenever the legend is valid (=add_nerd_icons_app=); =renderNerdIconsPreview= draws each row's glyph in its mapped face color through the shared registry, so recolor repaints live; the 34 faces stay editable. =#nerdiconstest= gate covers the wiring, the dir-row owner, and the recolor-repaint. Committed (feat phase 2).
*** 2026-06-24 Wed @ 05:54:34 -0400 Phase 3 — tint removed, theme drives color
Removed =cj/nerd-icons-tint-color= + =cj/--nerd-icons-color-faces= + =cj/nerd-icons-apply-tint= and both call sites from =nerd-icons-config.el=; the WIP theme already owned the 34 faces (theme-studio auto-discovered them), so color is theme-driven now. Kept =cj/--nerd-icons-color-dir=. Deleted the apply-tint test. validate-modules + launch smoke clean. Committed (feat phase 3).
*** 2026-06-24 Wed @ 05:54:34 -0400 Phase 4 — dir-precedence probe + round-trip
ERT probe locks the dir-precedence decision (prepended =nerd-icons-yellow= is first in the face list, wins over =nerd-icons-completion-dir-face=); =#nerdiconstest= extended with the export/import round-trip over an assigned nerd-icons color and a dir-face-stays-out check. Full run-tests.sh + =make test= green. Committed (test phase 4). Live visual is the VERIFY under Manual testing.
** DONE [#B] ai-term keybinding home :feature:
CLOSED: [2026-06-23 Tue]
Done 2026-06-23 (commit be772bc0): family moved to C-; a (a toggle, s select/launch, n next, k kill), swap also on M-SPC, F9 family retired, jumper's M-SPC binding removed (rehome pending). cj/ai-term-next now opens the picker when no agent is running instead of erroring. Bindings verified live in the daemon; Craig's hands-on check is filed under Manual testing and validation.
Move the ai-term commands off the F9 family. F9 sits somewhere semi-dangerous
to hit, and F8 (org-agenda) is slow to load, which reads as Emacs being
unresponsive. Craig wants three commands on an easy near-home-row chord: open
the ai-term selection menu, switch to the next agent, and kill the current one
(=cj/ai-term=, =cj/ai-term-next=, =cj/ai-term-close=). Explore C-, M-, and C-M-
with SPC. Likely collides with jumper, but ai-term is used far more, so jumper
yields. Archiving gptel this session freed the =C-; a= prefix, so the whole
ai-term family could live under =C-; a= (or another near-home-row key).
Related: the s-F9 detached-agent landing task and the tmux copy-mode binding
task elsewhere in this section. From the roam inbox.
** DONE [#C] Face coloring completion-read icons :quick:solo:
CLOSED: [2026-06-23 Tue]
Answered 2026-06-23 (investigation, no code change). There is no single
"completion icon" face — each icon inherits a per-type =nerd-icons-*= color
face (a .el file icon inherits =nerd-icons-purple=, an M-x command icon
=nerd-icons-blue=, etc.; nerd-icons picks the face per glyph/filetype). What
makes every completion icon render the SAME color here is this config's bulk
tint: =cj/nerd-icons-tint-color= (defcustom in =nerd-icons-config.el=, default
"darkgoldenrod") sets the foreground of all ~33 =nerd-icons-*= color faces via
=cj/nerd-icons-apply-tint=, applied in the =nerd-icons= =:config=. Verified live:
=nerd-icons-icon-for-file "init.el"= -> =:inherit nerd-icons-purple=, and that
face's foreground is "darkgoldenrod". Directory icons additionally get
=nerd-icons-yellow= layered on by =cj/--nerd-icons-color-dir= advice
(=nerd-icons-completion-dir-face= is unset, so it isn't the driver here).
To theme: change =cj/nerd-icons-tint-color= (one color for all icons, then call
=cj/nerd-icons-apply-tint=), or drop the bulk tint and set the individual
=nerd-icons-*= color faces for per-filetype colors. For theme-studio, the knob
to expose is =cj/nerd-icons-tint-color= plus the =nerd-icons-*= face family.
** DONE [#C] Org formatting inside cj comments :feature:
CLOSED: [2026-06-23 Tue]
Done 2026-06-23: mapped the "cj:" src-block language to org-mode via
=org-src-lang-modes= in =org-babel-config.el=.  Effect: a cj comment block's
prose now gets org font-lock in place (links, *bold*, lists styled — verified
live, the link inside a block carries the =org-link= face), and =C-c '= opens a
full org-mode buffer to edit it.  Approach A from the design walk: non-breaking,
the =cj:= grep marker and the whole cj-processing pipeline are unchanged.  The
block stays a src block, so org's parser still treats its body as code — links
are followed from the =C-c '= buffer rather than clicked in place.  If that
in-place limitation bites, Approach B (migrate to a =#+begin_cj= special block)
is the documented escalation.
Craig writes free-form prose inside cj comment blocks (=#+begin_src cj: ...=)
and wants org formatting available there.
From the roam inbox.
** DONE [#C] term: M-<arrow> enters tmux copy-mode :feature:
CLOSED: [2026-06-24 Wed]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-22
:END:
Done 2026-06-24: C-<up>/<down>/<left>/<right> and M-<arrow> in =ghostel-mode-map= enter copy-mode and carry their direction in one stroke (=cj/term-copy-mode-up= & friends -> =cj/term-copy-mode-move= -> =cj/term-copy-mode-dwim= then =cj/--term-copy-mode-move-step=). tmux path writes the arrow escape sequence into the pty; non-tmux path moves point in =ghostel-copy-mode=. All 8 keys added to =ghostel-keymap-exceptions= + =ghostel--rebuild-semi-char-keymap= (the gotcha). Ghostel-only. 6 new ERT tests; bindings + exceptions + the dwim sequence verified live in the daemon. The real tmux copy-mode scroll is a VERIFY under Manual testing and validation.

Folded 2026-06-23 from the roam inbox: Craig also wants C-<up> (control + up arrow) to enter tmux copy-mode and move up in one stroke — i.e. a modified arrow both enters copy-mode and passes the movement (copy-mode + arrow). So the binding set is the modified arrow keys (M-arrow and/or C-arrow), each entering copy-mode and carrying its own direction.
** DONE [#B] mu4e: cmail can't trash, no account can refile :bug:quick:solo:
CLOSED: [2026-06-24 Wed]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
=modules/mail-config.el:217-220= — the cmail context (primary account) sets only drafts/sent, so D falls back to default "/trash" which doesn't exist under ~/.mail (=/cmail/Trash= does); and NO context sets =mu4e-refile-folder=, so r targets nonexistent "/archive" everywhere. Accepting mu4e's offer to create the maildir strands mail in a directory mbsync never syncs — messages silently vanish from the server's view. Add =mu4e-trash-folder= to cmail + per-context =mu4e-refile-folder=. From the 2026-06 config audit.
Fixed 2026-06-13: cmail gets =mu4e-trash-folder= "/cmail/Trash"; refile is a per-message function (=cj/mu4e--refile-folder=) instead of a per-context string — mu4e context :vars are sticky, so a per-context refile leaks one account's archive folder into another. cmail → "/cmail/Archive"; gmail/dmail signal a =user-error= rather than move mail into an unsynced phantom folder (Craig chose the fail-safe over syncing [Gmail]/All Mail — the All Mail option means a multi-GB pull + cross-folder duplicates; revisit if local Gmail archiving is wanted). Applies on next mu4e open; pure dispatch helper covered by tests.
** CANCELLED [#B] AI Open Work
CLOSED: [2026-06-23 Tue]
gptel archived 2026-06-23 to archive/gptel/ (rarely used). The child issues below — ai-rewrite directive plumbing, ai-conversations bugs, the stale-elpa / gptel-magit shadow, model-switch dedup — are all moot against archived code. Kept for reference; detail also in git history.
*** CANCELLED [#B] ai-rewrite: chosen directive never reaches the request :bug:solo:
=modules/ai-rewrite.el:64= — the directive is let-bound around =(call-interactively #'gptel-rewrite)=, but gptel-rewrite is a transient prefix that returns when the menu shows; the send resolves the directive AFTER the binding unwound (verified against ~/code/gptel/gptel-rewrite.el:780-799). The picker's choice is silently dropped — the module's core feature is inert. Set =gptel--rewrite-directive= buffer-locally (restore via =gptel-post-rewrite-functions=) or use a self-removing global hook entry. From the 2026-06 config audit.

*** CANCELLED [#B] Stale elpa gptel shadows the local fork — likely the gptel-magit root :bug:quick:solo:next:
Needs from Craig: can't be done standalone. I tried deleting elpa/gptel-0.9.8.5 — the fork loaded fine and gptel-magit still worked via use-package autoloads, but package activation then printed "Unable to activate gptel-magit / Required gptel-0.9.8 unavailable" on every startup, so I reverted. To remove the shadow we must also resolve gptel-magit's package dependency: either drop gptel-magit's package dep (load it via load-path like the gptel fork), or repackage the fork into .localrepo as gptel. Tell me which and I'll do it; this pairs with the gptel-magit investigation.
=elpa/gptel-0.9.8.5= is still installed alongside the =~/code/gptel= fork (=ai-config.el:383=); package activation puts the elpa dir + autoloads on load-path, so which copy wins depends on ordering, and a mixed load (fork .el + elpa .elc) produces "impossible" bugs. =gptel-magit= (elpa) declares gptel as a dependency, so IT may be pulling the stale copy — check this first when working the open "[#B] Investigate gptel-magit not working properly" task. Fix: =package-delete= the elpa gptel + remove from .localrepo so the fork is the only copy on disk. From the 2026-06 config audit.

2026-06-15: tried deleting =elpa/gptel-0.9.8.5= standalone. The fork loaded correctly and gptel-magit still worked via use-package =:commands= autoloads, BUT package activation then printed "Unable to activate package gptel-magit / Required package gptel-0.9.8 unavailable" on every startup and test run (gptel-magit declares gptel as a package dependency that no longer resolves). Reverted. This can't be done standalone — it must be paired with the gptel-magit dependency fix (drop gptel-magit's package dep, or repackage the fork into .localrepo as gptel). Do it together with the gptel-magit investigation task.

*** CANCELLED [#B] ai-conversations: dead-buffer load, role flattening, non-atomic writes :bug:solo:
From the 2026-06 config audit, =modules/ai-conversations.el=:
- =:324= — load in a fresh session does =get-buffer-create "*AI-Assistant*"= (plain fundamental-mode buffer); =--ensure-ai-buffer= then sees it exists and never calls =(gptel)=. Sending doesn't work, autosave self-cancels (requires gptel-mode). Use =get-buffer= for the check; let ensure create. The browser RET/l path inherits this.
- =:240= — persistence drops gptel's =response= text properties, so a reloaded history replays to the model as ONE user message (model re-reads its own answers as Craig's words). Adopt gptel's native bounds persistence or re-mark on load from the "* Backend:" headings.
- =:248= — =write-region= straight at the target; crash mid-write truncates the only copy of the history (autosave hits this constantly). Temp + rename.
- =:140= — three overlapping autosave mechanisms (after-send advice that fires before the response exists, post-response hook, 60s timer). Keep the hook; drop the advice (and likely the timer).

*** CANCELLED [#B] Dedup gptel model-switch commands — keep switch-backend or fold into change-model :bug:
=cj/gptel-change-model= (C-; a m) already does backend+model switching and interns correctly, so =cj/gptel-switch-backend= (C-; a B) is arguably redundant now that its crash is fixed. Decision for Craig: keep both, or delete =cj/gptel-switch-backend= plus its C-; a B binding and keep one model-switch command. From the 2026-06 config-audit follow-up.
** DONE [#B] agenda sources: roam Projects missing, no existence filtering :bug:solo:
CLOSED: [2026-06-24 Wed]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
Done 2026-06-24, both parts: (1) per Craig, corrected the docs rather than implementing roam-Project agenda scanning — the commentary + two docstrings claimed org-roam "Project" nodes are agenda sources, but they were never scanned; roam Project/Topic notes are refile targets (org-refile-config.el), not agenda sources. (2) =cj/--org-agenda-base-files= now drops non-existent files and =org-agenda-skip-unavailable-files= is set as a backstop, in the one shared helper so the agenda builders, single-project view, and chime initializer all get it. base-files tests reworked to drive real temp files (+ a drops-missing case); byte-compile clean; live-verified (skip var t, base-files returns only existing). From the 2026-06 config audit, =modules/org-agenda-config.el=:
- =:182-191= — commentary and docstrings promise org-roam nodes tagged "Project" as agenda sources, but =cj/--org-agenda-scan-files= never scans them, and files added by the roam finalize-hook are wiped on the next =cj/build-org-agenda-list= cache rebuild (≤1h). Add a roam Project pass (mirror =org-refile-config.el:101-109=) or correct the docs.
- =:186,456= — agenda file list built unconditionally (inbox/calendars may not exist on a fresh machine) and =org-agenda-skip-unavailable-files= is unset — the exact interactive-prompt class that once hung the chime daemon. Filter with =file-exists-p= + set the var as backstop.
** DONE [#B] F7 diff-aware coverage classifies every changed file "not tracked" :bug:solo:
CLOSED: [2026-06-22 Mon]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
Fixed 2026-06-22: simplecov keys are absolute, git-diff keys repo-relative, so the exact-key intersect never matched. Added =cj/--coverage-relativize-keys= and normalize both tables to repo-relative in =cj/--coverage-read-and-display= before the intersect; intersect unchanged. New =test-coverage-core--relativize-keys.el= (5 unit + 1 integration through the real parsers). Full suite green.
=modules/coverage-core.el:252= — =cj/--coverage-intersect= joins covered×changed by exact string key, but simplecov.json keys are ABSOLUTE paths while the git-diff parser returns repo-RELATIVE ones — zero matches ever, so working-tree/staged/branch scopes report ":tracked nil" for everything and F7's main feature is inert (whole-project scope works, same-source keys). Unit tests hand-build matching keys so they pass; add one integration test feeding a real undercover report + real diff. Normalize both sides to repo-relative. From the 2026-06 config audit.
** DONE [#B] jumper: register collisions and dead-marker errors :bug:solo:
CLOSED: [2026-06-22 Mon]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-13
:END:
Fixed 2026-06-22: (1) store now allocates the first unused register char in the live slice (=jumper--first-free-register=) instead of by next-index, and removal clears the freed register, so a store after a removal no longer overwrites a surviving slot's marker; (2) =jumper--with-marker-at= guards =(buffer-live-p (marker-buffer marker))= so killed-buffer entries are skipped instead of signaling wrong-type errors; (3) the single-location toggle jumps back to the last-location register when set (returns =jumped-back=). New =test-jumper--register-hygiene.el= (8 tests); all 42 jumper tests green. Pre-existing unused-lexical =i= warning in =jumper--location-exists-p= left alone (separate nit).
Two related defects from the 2026-06 config audit:
- =modules/jumper.el:155= — removal shifts the vector without renumbering registers, so a later store allocates a register still held by a surviving location and silently overwrites it. Allocate the first free register char in the live slice; =set-register nil= on removal so freed markers don't pin buffers.
- =modules/jumper.el:117,132= — guards check =(markerp marker)= but not =(buffer-live-p (marker-buffer marker))=; after killing a buffer holding a location, M-SPC SPC and M-SPC j signal wrong-type errors. Treat dead entries as skippable/removable.
Also =jumper.el:178= — the promised single-location toggle never toggles back ('already-there branch should =jump-to-register= z when set).
** DONE [#C] face-diagnostic: face-name buttons + header allowlist :feature:quick:solo:
CLOSED: [2026-06-24 Wed]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Done 2026-06-24: (a) =cj/--face-diag-face-button= renders each real face name in the report as a =buttonize='d button that runs =describe-face= on it (carries the face as button-data); anonymous specs and non-faces stay plain. Routed through the stack, overlay, remap, and provenance render sites. (b) Added =face-diagnostic= to =test-init-header--classified-modules= (it's required in init.el and already carries the header contract). 5 new ERT tests; button text properties confirmed live in a rendered *Face Diagnosis* buffer. Click/RET sign-off is a VERIFY under Manual testing and validation. Spec: [[id:98f065cf-8bd5-46a0-ac24-da94d66855ad][face-font-diagnostic-popup-spec-implemented.org]].
** DONE [#C] latexmk workflow never activates (two breaks) :bug:quick:solo:
CLOSED: [2026-06-24 Wed]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Done 2026-06-24: changed the :hook key from =TeX-mode-hook= to =TeX-mode= (use-package appends "-hook" only to non-"-mode" symbols, so this now registers on the real =TeX-mode-hook= instead of the unbound =TeX-mode-hook-hook=), and auctex-latexmk from =:defer t= to =:after tex= so =auctex-latexmk-setup= runs when AUCTeX loads. Confirmed both breaks via macroexpand (the dump showed =add-hook 'TeX-mode-hook-hook= before, =TeX-mode-hook= after). 2 new regression ERT tests; live-verified in a real .tex buffer: =TeX-command-default= is "latexmk" and "LatexMk" is in =TeX-command-list=. Actual C-c C-c compile is a VERIFY under Manual testing and validation. From the 2026-06 config audit.
** CANCELLED [#B] first f12 doesn't toggle the term window :bug:solo:
CLOSED: [2026-06-25 Thu]
Couldn't reproduce — neither could Craig (2026-06-25). The toggle code is clean (a single create-new -> ghostel on the first press, no second toggle), and the symptom pointed to an intermittent first-launch race, but with nobody able to reproduce it there's nothing to instrument. Cancelled; reopen with a live capture if it recurs.
** DONE [#B] F12 pops EAT instead of ghostel :feature:studio:
CLOSED: [2026-06-25 Thu]
Done 2026-06-25, design doc =docs/design/eat-f12-toggle.org=. Part A (commit fe7aa658): F12 toggles a single EAT terminal instead of ghostel, reusing the dock-and-remember geometry toggle; ghostel stays for ai-term (M-SPC); EAT runs a plain shell with no tmux; F12 and C-; are bound in EAT's keymaps so they reach Emacs from inside the terminal. Part B (commit 687b438f): EAT's faces are exposed in theme-studio (16 named palette + attribute + prompt-annotation faces) with a =renderEatPreview=, no colors set so it stays vanilla. term 223/223, ai-term 158/158, studio gates green; the toggle wiring (F12 reaches Emacs in EAT, =(eat)= creates the buffer, the predicate recognizes it) was verified live in the daemon. Accepted tradeoff: EAT needs a buffer reload to pick up a theme switch (ghostel auto-resyncs), taken for EAT's pure-elisp face control. The visual F12 dock/toggle check is a VERIFY under Manual testing and validation.
** DONE [#B] Consolidate on EAT, retire ghostel :feature:refactor:
CLOSED: [2026-06-27 Sat]
Make EAT the only terminal and remove ghostel entirely (decision 2026-06-25). Phased; the ai-term port (Phase 3) wants its own focused session with a spike first.
- Phase 1 DONE (commit 82294404): extracted =modules/eat-config.el= (eat package + F12/C-; keymaps + the F12 dock-and-remember toggle) out of =term-config.el=. term-config keeps ghostel (ai-term's backend) and requires eat-config. Toggle tests retargeted to eat-config; full suite green.
- Phase 2 DONE (commit 0290b015): EAT experience settings in eat-config.el -- yank-to-terminal on, directory-tracking / prompt-annotations / command-history / mouse / kill-from-terminal / alt-screen affirmed, 10MB scrollback, truecolor already on via the compiled =eat-truecolor= terminfo. zsh shell-integration source line added to =~/.dotfiles/common/.zshrc= (uncommitted -- needs a dotfiles commit + a pull on the other daily driver).
- F12 = eshell-through-EAT (2026-06-25, commits cbd38d88 + c99fad28): F12 now opens eshell run through EAT (eat-eshell-mode) instead of a standalone EAT zsh shell, so the primary terminal is eshell (elisp functions as commands, TRAMP transparency) with EAT rendering visual commands. Retired eshell-toggle + xterm-color; added a zsh-parity prompt (git branch + [N] exit status) and a zoxide =z= sharing the zsh database. eat-config + eshell-config kept separate.
- Phase 3 DONE (commit 6c8f2a9c): ported ai-term from ghostel to EAT. The spike confirmed EAT + tmux detach/reattach behaves exactly like ghostel + tmux (eat spawns, sends =tmux new-session -A -s aiv-<project>=; killing the buffer leaves the session alive; respawn reattaches). The coupling was far smaller than feared -- most of the ~30 refs were comments, and agent detection is name-based ("agent [...]"), so backend-agnostic. Swaps: =(ghostel)= -> =(eat)= with =eat-buffer-name=, =ghostel-send-string= -> a process-send-string helper, M-SPC bound directly in =eat-semi-char-mode-map= (no exception/rebuild dance). 157 ai-term tests green. Real-agent launch + detach/reattach is a VERIFY under Manual testing and validation.
- Phase 4 DONE (commit 6a9ec62e): retired ghostel. Migrated the terminal-generic keepers into eat-config -- the tmux copy-mode (=C-<up>= enters it, same UX + keybinding; agents run EAT over tmux so it's still tmux's own copy-mode) and the tmux-history capture, swapping =ghostel-send-string= -> a pty write and the mode checks -> eat-mode. Repointed the dashboard "Launch Terminal" to =cj/term-toggle=, swapped the =face-diagnostic= terminal-mode check to eat-mode, refreshed the auto-dim comment. Deleted =term-config.el= + its init require. EAT's default =eat-semi-char-non-bound-keys= already lets windmove / buffer-move / Emacs keys reach the terminal, so no exception-list port was needed. Tests retargeted (tmux-history 15/15). The copy-mode + tmux-history live check is a VERIFY under Manual testing and validation.
- Phase 5 DONE (commit eb4aa232): removed the theme-studio ghostel app (=GHOSTEL_FACES=) now those faces are dead (ansi-color stays -- EAT inherits it), =package-delete='d the ghostel ELPA package, and swept the remaining ghostel mentions in comments/docs. The optional F8/F10 surfacing in agent buffers was not pursued.
** DONE [#C] ai-term.el commentary names a stale F9 keybinding scheme :quick:solo:
CLOSED: [2026-06-28 Sun]
Rewrote the header Commentary (the "four global keys" + "Four F-key entry points: F9 / C-F9 / s-F9 / M-F9" block) to the current scheme: the =C-; a= prefix map (a = toggle, s = select/launch, n = next, k = kill) plus the global =M-SPC= -> =cj/ai-term-next=. Fixed the binding-claiming docstrings (=cj/ai-term=, =cj/ai-term-pick-project=, =cj/ai-term-shutdown=, =cj/--ai-term-dispatch=) and swept the behavioral =F9= shorthand + two stray =C-F9= claims in internal docstrings. Kept the two historical incident names ("F9 shrink bug", "F9 shows another agent" bug) as recorded references. Doc-only: parens ok, no new byte-compile warnings, dispatch tests 4/4, live-reloaded.
** CANCELLED [#C] ai-term: fullscreen on summon, toggle when only one agent :feature:
CLOSED: [2026-06-28 Sun]
Cancelled — rethinking the ai-term window behavior before committing to an approach.
Two behaviors for M-SPC (=cj/ai-term-next=) when bringing up an agent from a non-agent context:
1. Summon fullscreen. Today the agent opens in its deliberate dock — 0.75 frame height on a laptop (=cj/ai-term-laptop-height=), a width fraction on desktop (=cj/--ai-term-default-size= / =-default-direction=) — so summoning from another buffer lands it at partial size and Craig hits =C-x 1= to fill the frame. When summoning (no agent window currently shown), open it fullscreen instead.
2. Single-agent toggle. When exactly one agent exists, M-SPC currently self-cycles (=cj/--ai-term-next-agent-dir= wraps to the same dir, re-selecting the same window — a no-op). Repurpose it: with one agent, M-SPC toggles the window (show fullscreen if hidden, hide if shown), matching =cj/ai-term= (C-; a a). With 2+ agents, keep the cycle behavior.
Touches the dock/toggle state machine (=cj/--ai-term-last-direction= / =-size= / =-was-bury= etc.), so implement carefully and keep the multi-agent cycle plus toggle-restore reversibility intact. From the roam inbox.
** DONE [#C] dashboard: no icon for URL bookmarks :bug:
CLOSED: [2026-06-28 Sun]
Resolved by dropping per-item list icons rather than adding a URL glyph: set =dashboard-set-file-icons nil= (=dashboard-config.el=), so recents / bookmarks / projects render without leading icons and URL vs file bookmarks look uniform. Section-heading icons and the launcher row keep theirs. Verified live: the =*dashboard*= buffer's bookmark/project items render glyph-free (the URL bookmark "Tensegrity Blog" now matches the file bookmarks). From the roam inbox.
** DONE [#B] calendar-sync robustness: atomic writes, curl --fail, zero-event false errors :bug:solo:next:
CLOSED: [2026-06-25 Thu]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
All three landed (commit 11049db5) and verified against the live feed — gcal/pcal/dcal all fetched and wrote cleanly. (1) =calendar-sync--write-file= and =--save-state= write a temp file in the same directory then =rename-file= it into place, so a mid-write reader never sees a partial calendar. (2) Both curl fetches got =--fail=, so an HTTP 404/500 page exits non-zero instead of flowing its HTML into conversion. (3) =--parse-ics= now distinguishes a healthy zero-event calendar (real =BEGIN:VCALENDAR=, no in-window events -> header) from garbage (no VCALENDAR -> nil), so near-empty calendars no longer report "parse failed". New robustness tests + the empty-calendar boundary test corrected; calendar-sync suite 575/575.
** DONE [#B] org-roam :config triggers the 15-20s refile scan synchronously at first idle :bug:solo:next:
CLOSED: [2026-06-25 Thu]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
Fixed (commit 4e48432c): removed the redundant =cj/build-org-refile-targets= call from org-roam's :config (=org-roam-config.el=). org-roam is =:defer 1=, so that call ran the multi-file refile scan synchronously at the 1s idle on a cold cache, freezing Emacs at first idle; =org-refile-config.el= already schedules the same build on a 5s idle timer, so it was a duplicate. The first-idle freeze is gone. This removed the *duplicate* early scan, not the scan's cost — making the scan itself faster stays the separate =[#B] Optimize org-capture target building performance= task (profile-first).
** DONE [#B] transcription: stderr never reaches the log :bug:solo:next:
CLOSED: [2026-06-28 Sun]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-25
:END:
The "/tmp" half was DONE earlier (commit 3d9a650d): video transcripts land beside the source video via an =output-base= threaded through =cj/--start-transcription-process=.
The stderr half is now fixed: =make-process :stderr= had a file PATH, which Emacs turns into a phantom buffer named after the path — so the error text never reached the log and a buffer leaked per run. Fix (2026-06-28): an explicit, erased stderr buffer (=" *transcribe-stderr-<file>*"=) is passed to =:stderr=, threaded to the sentinel, drained into the log file via =cj/--append-to-log=, then killed. Keeping stderr off the stdout =:buffer= leaves the transcript clean. TDD: new =test-tx-start-process-stderr-is-a-buffer-not-a-path= plus strengthened sentinel tests asserting the stderr text reaches the log and the buffer is killed; full transcription suite 39/39 green; live-reloaded.
Live failing-run confirmation is filed under "Manual testing and validation".
** DONE [#B] eww User-Agent advice may not inject under Emacs 30 :bug:
CLOSED: [2026-06-25 Thu]
Root cause was NOT =derived-mode-p= (that works in both batch and the daemon — my initial guess was wrong). It was the lexical-binding special-var trap: =eww-config.el= is =lexical-binding: t= and the advice =my-eww--inject-user-agent= let-binds url.el's =url-request-extra-headers=, but the file never declared that var special. The byte-compiler bound it lexically, so the injected User-Agent never reached =url-retrieve= and the desktop UA silently dropped in compiled production (eww still worked, just with the default UA). Verified: the byte-compiled advice returned nil before, =t= after. Fix (commit 6131da8e): a top-level =(defvar url-request-extra-headers)= so the compiler treats it as dynamic and the binding propagates. All 3 advice tests pass; live-reloaded. Same class as the json-object-type and the LSP-test special-var traps — a foreign special var let-bound in a lexical file always needs a compile-time defvar/require.
** DONE [#B] calendar-sync: a declined single occurrence keeps :STATUS: accepted :bug:solo:
CLOSED: [2026-06-25 Thu]
A recurring event declined for just one occurrence synced out with =:STATUS: accepted= (chime then faithfully showed it). Root cause (diagnosed by a chime session, 2026-06-24): =calendar-sync--apply-single-exception= merged the override's =:attendees= but never re-derived =:status=, so the occurrence kept the series master's accepted status, and =calendar-sync--filter-declined= (which keys off =:status=) didn't drop it. Fix (TDD): in =apply-single-exception=, when overriding =:attendees=, re-derive =:status= via =calendar-sync--find-user-status= against =calendar-sync-user-emails=. Four new tests in =test-calendar-sync--apply-single-exception.el= (declined → "declined"; no-attendee override → inherited intact; accepted override → accepted; override without the user → inherited intact); recurrence + find-user-status + integration suites unchanged. Live-reloaded; a manual re-sync ran clean. The specific 2026-06-24 Arusyak occurrence is past now (its RECURRENCE-ID override aged out of the feed), so the live confirmation lands on the next single-occurrence decline.
** DONE [#C] ledger-config is orphaned — ledger-mode never configured :bug:quick:
CLOSED: [2026-06-28 Sun]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-21
:END:
Resolved by wiring (Craig's call 2026-06-28: wire it, not delete). Already landed in commit 6ec857ae (2026-06-24, "feat(ledger): un-orphan ledger-config and rewrite clean-on-save") — =init.el:123= now requires =ledger-config=, after this task's 2026-06-21 review, so the task was stale. Confirmed it loads cleanly; the =cj/executable-find-or-warn "ledger"= guard is in its =:config=. Follow-on audit + guardrail-UX work filed as its own task below.
** DONE [#C] Remove unused system-power keybindings :refactor:quick:solo:
CLOSED: [2026-06-28 Sun]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
Removed the per-command leaf keys (s/r/e/l/L/E/S) under =C-; != and the prefix map. =C-; != now binds directly to =cj/system-command-menu= (the completing-read menu), via =cj/register-command=, so every command stays reachable through the menu and the leaf keys are freed. Updated the module commentary and the two keymap tests (now assert the direct-command binding + no submap; the menu-dispatch test already covers reachability). 2/2 keymap + 18/18 system-cmd tests green; live-reloaded; confirmed =C-; != resolves to =cj/system-command-menu=. Decision was Craig's (2026-06-28, cj comment): remove them all.
** CANCELLED [#C] dirvish image previews missing in the pictures dir :bug:
CLOSED: [2026-06-25 Thu]
Craig couldn't reproduce — image previews render fine in dirvish now. Cancelled.
** DONE [#C] ai-term test isolation: collapse-split leaks state breaking display-rule :bug:test:
CLOSED: [2026-06-25 Thu]
Root cause found: the display rule's 4th action =cj/--ai-term-display-saved= splits per the globals =cj/--ai-term-last-direction= / =cj/--ai-term-last-size=, captured on the last toggle-off. The collapse-split multi-window and single-window tests call =cj/ai-term= (which captures those globals) but only let-bound =cj/--ai-term-last-was-bury=, so they leaked =last-direction= = below into =display-rule=, which then split below (left-col 0) instead of right (left-col 40). Confirmed by instrumenting: every window/split global was identical fresh vs after-collapse, but the leaked =last-direction= flipped the directional split. Fix: let-bind =cj/--ai-term-last-direction= + =cj/--ai-term-last-size= to nil in both collapse-split tests, isolating the capture-state globals the way the roundtrip test in the same file already does. Full ai-term suite now 158/158 green.
** DONE [#C] dirvish leaves stray buffers; should be single-instance like org-capture :bug:
CLOSED: [2026-06-25 Thu]
Diagnosed and fixed (commit e190648b). The single-instance frame behavior already existed (=cj/dirvish-popup-focus-existing= raises the open popup on a second Super+F; =q= tears it down). Measured the litter: navigating a dirvish session piles up one dired buffer per directory (2 -> 6 over three subdirs), but =dirvish-quit= reaps them all back to baseline. So the leak was only when the popup is closed WITHOUT =q= — closing the Hyprland float or losing focus bypassed =dirvish-quit= and orphaned the session's buffers. Fix: a =delete-frame-functions= hook scoped to the "dirvish" popup frame runs =dirvish-quit= on every close path (verified: navigated session drops back to baseline on frame close without q). Deliberately did NOT enable =dired-kill-when-opening-new-dired-buffer= — it's off on purpose (dirvish-config.el:208) because it breaks mark-in-A-then-move-to-B; the popup-scoped reap leaves regular =C-x d= sessions and that workflow untouched.
** DONE [#C] ai-term: step between running ai-terms even when detached :feature:solo:next:
CLOSED: [2026-06-25 Thu]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-22
:END:
Implemented 2026-06-25 (commit 79cbccb5): =cj/ai-term-next= now cycles every active agent (a live buffer OR a live tmux session) keyed on the project dir and ordered by buffer name, and stepping onto a detached one attaches it (=cj/--ai-term-show-or-create= recreates the terminal, which reattaches the session). New pure helpers =cj/--ai-term-next-agent-dir= + =cj/--ai-term-active-agent-dirs= with 10 ERT tests; the live-buffer swap path is unchanged. Live check filed under Manual testing and validation.
** DONE [#C] Compare terminal themeability: EAT vs vterm vs ghostel :feature:solo:next:
CLOSED: [2026-06-25 Thu]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-22
:END:
Researched 2026-06-24. All three expose the 16 ANSI colors as Emacs faces (=eat-term-color-*=, =vterm-color-*=, =ghostel-color-*=, each inheriting =ansi-color-*= / =term-color-*=). Ghostel is the most live-themeable: it alone registers an =enable-theme-functions= resync hook (repaints live buffers on a theme change) and exposes a dedicated =ghostel-default= face for the terminal's default fg/bg. EAT (pure elisp, where the faces are the real render source) and vterm (native, faces read at render) both expose themeable palettes but need a buffer reload to pick up a theme switch and give less default-fg/bg control. Outcome: Craig is moving F12 to EAT anyway, for pure-elisp face control and the fun of theming it — see "F12 pops EAT instead of ghostel" above, which carries the resync tradeoff knowingly.
** CANCELLED [#D] Un-pin ghostel from 0.33.0 once upstream fixes #422/#423 :bug:
CLOSED: [2026-06-26 Fri 04:56]
:PROPERTIES:
:LAST_REVIEWED: 2026-06-20
:END:
ghostel is held at 0.33.0 (=ghostel-20260604.2049=, commit 5779a2adceb2) in =modules/term-config.el= to dodge the 0.35.x native-PTY crash. When dakra/ghostel ships a fix for #422 (Linux malloc/signal reentrancy) and #423 (macOS recursive lock), restore =:ensure t= (drop the pin comment) and =package-upgrade ghostel=, then re-run the open-ghostel-in-a-GUI-frame survival check. Watch the two issues for the fixing commit.

archsetup automated the zig 0.15.2 pin (managed =install_zig_pin= step, sha-verified, unit-tested). If the un-pinned ghostel bumps its ghostty dependency to a newer zig, send archsetup the new version + sha256 so it bumps its =ZIG_VERSION= / =ZIG_SHA256= constants (=inbox-send archsetup=).
** DONE [#C] EAT diff green and red too bright :quick:
CLOSED: [2026-06-28 Sun]
Darkened the added/removed line backgrounds. Added =eat-term-color-22= (added green) and =eat-term-color-52= (removed red) to the eat section of =scripts/theme-studio/WIP.json= at about half their former brightness — =#005F00= -> =#002f00=, =#5F0000= -> =#2f0000= (Craig: pick an appropriate darkness from WIP.json; halved, symmetric, still clearly green/red). Regenerated =themes/WIP-theme.el= via build-theme.el and re-applied the WIP theme live in the daemon (confirmed: =eat-term-color-22= = #002f00, =-52= = #2f0000). EAT uses each face's :foreground as the palette value for both fg and bg paint, so darkening the foreground darkens the diff background.
Scope notes: (1) the green index (22) was confirmed via =C-h F=; the red (52) is the symmetric ANSI-256 dark-diff counterpart — if removed lines don't darken, the real index needs a live sample. (2) Only the line backgrounds are themed; the brighter within-line word-highlight shades are different (unconfirmed) indices, left for a live sample if Craig still finds them bright. (3) A 256-cube override is global (hits every terminal program emitting color 22/52). (4) Studio round-trip caveat: a future studio re-export may drop these cube faces until the studio formally tracks them. Visual darkness confirm filed under "Manual testing and validation".
** DONE [#B] eat semi-char mode swallows zoom-out :bug:solo:
CLOSED: [2026-06-27 Sat]
Shipped in commit 69fee81f: =eat-semi-char-mode-map= now binds =C--= -> =text-scale-decrease= and =C-0= -> =cj/eat-text-scale-reset= (=eat-config.el:495-496=). Original report below.
In =eat-semi-char-mode= (the AI session buffers) =C--= is bound to =eat-self-input= and forwarded to the terminal, so it never reaches =text-scale-decrease= and the font can only grow. On velox 2026-06-27 a session climbed to text-scale 17 (~20x, unreadable) with no in-buffer way down. Fix (binding in =eat-semi-char-mode-map= works for eat, unlike ghostel): =C--= to =text-scale-decrease=, =C-0= to =(text-scale-set 0)=. Tradeoff: =C--= no longer forwarded to the terminal (Claude TUI and tmux do not use it), =C-0= shadows =digit-argument= inside eat buffers only. From the home-emacs inbox handoff 2026-06-27. Roam KB 799e8ab5-1c2c-4874-9abc-dff2ec354181.
** DONE [#C] restart-emacs no-service test fails on machines with emacs.service :test:bug:
CLOSED: [2026-06-29 Mon]
=test-system-cmd-restart-emacs-no-service-aborts= mocked =cj/system-cmd--emacs-service-available-p= directly, but =cj/system-cmd-restart-emacs= (natively compiled) reaches that helper through an intra-file direct reference in its =.eln= that bypasses the symbol-function redefinition, so the real check ran and passed on velox (which has =emacs.service=). Fixed by mocking at the boundary the helper uses (=executable-find= -> nil) instead of the helper itself, matching the passing sibling tests; the helper's =executable-find= call goes through a subr trampoline that honors =cl-letf=. 19/19 green.
** DONE [#C] dashboard: add a weather entry (wttrin) with an icon :feature:
CLOSED: [2026-06-28 Sun]
Shipped (a8a04377): a Weather launcher on key =w= in the dashboard top row after Agenda, drawn with the =nf-weather-day_sunny_overcast= Weather Icons glyph (Craig picked it from a rendered candidate set). It opens the wttrin forecast via =call-interactively= so the location prompt runs (a bare =(wttrin)= errors -- the location is a required arg supplied by the interactive form). Row sizes 4-4-3-3 -> 5-4-3-3; launcher-table tests updated. Verified live by Craig.
** DONE [#C] ai-term: M-SPC summon ignores the agent's last fullscreen size :bug:
CLOSED: [2026-06-28 Sun]
Fixed via Approach B (geometry tracking). A =window-configuration-change-hook= tracker (=cj/--ai-term-track-geometry=) records whether a displayed agent window is the sole window of its frame into =cj/--ai-term-last-fullscreen=; =cj/--ai-term-display-saved= restores the agent in place (fullscreen) when that flag (or the existing bury flag) is set and the frame is a single window, otherwise docks as before. Two follow-on bugs surfaced and were fixed during live testing: (1) the tracker must NOT re-capture dock direction/size on every window change -- doing so fed a capture/replay loop that drifted the dock height ~2 rows per cycle (the F9 shrink-bug class), so the tracker tracks only the fullscreen flag and leaves dock geometry to the toggle-off capture; (2) the restore condition used a bare =one-window-p=, which counts an active minibuffer (a picker prompt mid-summon) as a second window and misfired the restore into a dock that then cascaded -- fixed with =(one-window-p t)= (NOMINI). 5 new ERT tests in =test-ai-term--single-window-toggle.el=; 162/162 ai-term tests green; verified live by Craig (window holds (0 0 141 43) across round-trips). From Craig 2026-06-28.
** DONE [#C] Completion categories for the file-basename pickers :feature:solo:
CLOSED: [2026-06-29 Mon]
Done in commit 4d644374. Added =cj/completion-file-annotator= to system-lib (a candidate->path annotation factory showing size + date, "dir" for directories) and wired all eight pickers through =cj/completion-table-annotated= with a per-site category + resolver: timer sounds, drill flashcards, Info files, test-runner focus add + remove, vc clone dirs, hugo drafts, agenda projects (the project's todo.org mtime). music-config's existing table gained the category + annotator inline, keeping its sort metadata. Candidates and return values are unchanged (annotation-only); the six modules lacking it now require system-lib. Helper got Normal/Boundary/Error tests; full suite green at 5394. The marginalia render is a visual check, filed under Manual testing and validation.

Original task body: Eight =completing-read= pickers list bare file basenames, so marginalia can't annotate them: chrono-tools sounds, org-drill flashcards, help-config Info files, test-runner tests, music-config files, vc-config clone dirs, plus hugo drafts and org-agenda projects. For each, either make the candidates absolute paths so the standard =file= category resolves them, or tag a custom category with a small annotator. Decide per site. Helper =cj/completion-table= is in =system-lib=.