# Working With Craig's Running Emacs

Applies to: `**/*.el` (and any task that edits Craig's Emacs configuration)

Craig works inside Emacs nearly constantly, with a long-running `emacs --daemon` and `emacsclient` frames. When you edit an Emacs module he's using, **do not make him quit, relaunch, and re-open all his files.** Push the change into the running daemon instead. He explicitly called the restart-and-reload-everything dance out as the thing this avoids.

## Live-reload a module

After editing a module, reload it into the running daemon:

    emacsclient -e '(load "/home/cjennings/.emacs.d/modules/foo.el")'

This re-evaluates the file and redefines its `defun`s live. For straight function redefinitions it is immediate and clean — the edited command is active on the next keypress, no restart.

## Caveats — when a plain reload isn't enough

- **`defvar` defaults don't re-apply.** `defvar` only assigns when the variable is unbound, so reloading the file won't change an already-set default. `setq` the value explicitly, or `makunbound` it then reload.
- **`use-package` `:config` / `:init` re-run on a full file `load`.** That re-adds hooks, re-binds keys, re-runs setup — functionally fine, but it stacks state and isn't pristine. For an edit inside a `:config` block, prefer eval-ing just the changed form, or accept the restacking, or restart for a clean state.
- **Faces and themes need re-applying.** Editing a theme/face file does nothing until the theme is re-applied: `(load-theme 'THEME t)`.
- **Baked or rendered state must be regenerated.** Values computed at load time (e.g. a list built from `nerd-icons-*` calls) and already-drawn buffers (e.g. `*dashboard*`) do not update from a var reload alone — regenerate them (e.g. `dashboard-refresh-buffer`). This is the stale-buffer trap: the variable looks correct but the visible buffer is old. It once made a screenshot look right when the live buffer was still wrong.
- **`auth-source` caches credentials for two hours.** Editing `authinfo.gpg` (or syncing in a fresh copy) does not take effect in the running daemon until `(auth-source-forget-all-cached)`. The result cache holds both positive and negative lookups for `auth-source-cache-expiry` (default 7200s), so a key you just added still reads as "not set" until the cache clears or Emacs restarts. Symptom: a freshly-added credential keeps erroring as missing even though the entry is in the file. Fix: `emacsclient -e '(auth-source-forget-all-cached)'`, then re-trigger the lookup. (2026-06-01, diagnosing a Linear/pearl "API key not set" after the key landed in authinfo via a dotfiles sync.)

## The reload-and-verify loop (default for visible Emacs changes)

1. Edit the module.
2. Reload into the daemon (`emacsclient -e '(load ...)'`), plus re-apply the theme and/or regenerate the affected buffer where the caveats above apply.
3. Verify: for visual changes, screenshot and read it (the `screenshot.py` tool under `.ai/scripts/` can capture an app off-screen on a headless output); for behavior, eval or exercise it.

This replaces the quit → relaunch → re-find-and-load-files cycle for most edits. A real restart stays the gold standard for a guaranteed-clean state — anything touching `:config`, load order, or when in doubt.

## Don't edit on disk a file the daemon is capturing into

The reload caveats above are about pushing changes *into* the daemon. The inverse hazard: a tool that edits a file *on disk* while the daemon has an indirect buffer cloned from it. org-capture works through such a buffer, and a disk write (a hand edit, a `git pull` that fast-forwards the file, a `sed`/Write) reverts the base buffer underneath the capture. The capture is left on stale state, can no longer finalize with `C-c C-c`, and a freshly-typed item can be lost or written back against post-edit content. Orphaned `CAPTURE-*` buffers piling up as Craig retries is the visible symptom.

The roam inbox (`~/org/roam/inbox.org`) is the live case — Craig captures into it constantly, and inbox-zero's Phase D edits it. Before a disk write to a file the daemon may be capturing into, check first: `.ai/scripts/capture-guard <file>` exits non-zero (and names the buffer) when a live capture is cloned from `<file>`, and exits 0 — safe — when there's no capture or no reachable Emacs. Same principle as the reload rule, one layer out: leave the daemon's live buffers authoritative rather than yanking the file from under them.