> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jylhis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Package Reference

> Every Emacs package Jotain ships, with the reason it is included

{/* Refresh with `just docs-refresh-packages`. The flake check `packages-doc-in-sync` verifies this file matches the source. */}

# Package Reference

Auto-generated from `;;; @doc` markers immediately above each
`(use-package …)` form in `lisp/init-*.el`. To change a description,
edit the source file and run `just docs-refresh-packages`.

See the module-level narrative under
[Architecture → Modules](/architecture/modules) for higher-level
grouping.

## `init-core.el` — Core baseline

### `emacs` *(built-in / Nix)*

Sane defaults for the bare editor — fill column, dialog/box use,
lockfiles, recursive minibuffers, case-insensitive completion.
Settings here are the ones that don't deserve their own module.

### `saveplace` *(built-in / Nix)*

Persist point per file across sessions. Built-in. The advice
below recenters the buffer after restore so you don't reopen on
the bottom line.

### `diminish`

Hides minor-mode lighters from the modeline. Loaded early and
:demand t so that downstream use-package blocks can use the
:diminish keyword without macro-expansion errors.

### `files` *(built-in / Nix)*

Built-in file-handling tweaks: no auto-save side files, no
backup `~` files, no kill-process confirmation, plus a hook that
auto-creates missing parent directories on find-file.

### `repeat` *(built-in / Nix)*

Repeat-mode lets you press the trailing key alone after a prefix
command (e.g. C-x o o o instead of C-x o C-x o). Built-in,
enabled globally. \`repeat-exit-timeout' clears the transient map
after two idle seconds so the user doesn't have to think about
exiting it — the ergonomic "one-shot modifier" pattern. A
window-resize repeat-map filling the one gap in the built-in
coverage lives in init-keys.el.

### `uniquify` *(built-in / Nix)*

Disambiguate same-name buffers by directory prefix instead of
the default `<2>` suffix. `forward` style mirrors the path.

### `ibuffer` *(built-in / Nix)*

Replace `list-buffers` (C-x C-b) with the more capable ibuffer:
dired-style filter/mark/operate on buffers.

### `ffap` *(built-in / Nix)*

Tame `find-file-at-point` so an unknown hostname doesn't block
the editor on a DNS lookup — reject means "treat as not a host".

### `time` *(built-in / Nix)*

Built-in `world-clock` for cross-timezone scheduling. Loaded on
demand only.

### `exec-path-from-shell`

Inherits PATH, MANPATH, and other shell-managed vars from the
user's login shell so GUI / launchd / systemd-spawned Emacs
matches what the terminal sees. module.nix prepends Nix-store
binaries (rg, fd, git, direnv, coreutils) to the wrapper's
PATH — this picks up \~/.nix-profile and user toolchains.

### `autorevert` *(built-in / Nix)*

Auto-revert buffers when the underlying file changes on disk —
essential for branch switches and external edits. Also covers
non-file buffers (dired, magit) so they refresh too.

### `recentf` *(built-in / Nix)*

Built-in recently-visited files list. Used by consult-recent-file
and the bookmarks UI; state file lives under var/ to keep the
repo root clean.

### `savehist` *(built-in / Nix)*

Persist minibuffer history (M-p / M-n, vertico ordering, etc.)
across sessions. Built-in, enabled globally.

### `bookmark` *(built-in / Nix)*

Built-in bookmark store. State file is themed under var/ so it
joins the rest of Jotain's persistent state. `save-flag 1` writes
on every change so an Emacs crash never loses bookmarks; the fringe
glyph is suppressed because it adds visual noise without info.

### `isearch` *(built-in / Nix)*

Lazy-count isearch matches in the prompt — "(3/12)" tells you
where you are without leaving the search.

### `shr` *(built-in / Nix)*

Built-in HTML renderer used by eww, gnus, elfeed. Suppress page
colours and proportional fonts so rendered HTML inherits the
theme and the user's monospace face — better contrast,
predictable layout.

## `init-keys.el` — Global keys

### `emacs` *(built-in / Nix)*

Top-level rebindings — disable accidental suspend (C-z and
C-x C-z), put other-window on M-o for one-key window switching,
bind C-x j to the two-window rotate helper above, and rebind
C-g to the DWIM quit so it closes minibuffers from elsewhere.

### `windmove` *(built-in / Nix)*

Built-in directional window switching — `Shift-<arrow>` moves
focus between split windows. Ships with Emacs; no reason not
to turn it on globally.

## `init-ui.el` — UI: theme, modeline, fonts

### `auto-dark`

Flips between `jotain-theme-light` and `jotain-theme-dark`
following the system appearance — works on macOS, GNOME, and
anything that exposes a dark/light setting. C-c t toggles
manually.

### `doom-modeline`

A dense, IDE-style modeline with LSP/eglot status, project
buffer info, and Nerd Font glyphs. Loaded after init so the
primary frame doesn't redraw before fonts are ready.

### `emoji` *(built-in / Nix)*

Built-in emoji picker (Emacs 29+): `C-x 8 e e' inserts by name,
`C-x 8 e s' searches, `C-x 8 e l' opens the full list, `C-x 8 e d'
describes the emoji at point.  \`which-key' surfaces the prefix.

### `display-line-numbers` *(built-in / Nix)*

Built-in line numbers — only on programming and config buffers,
never on prose or org files where they're noise. Honour the
\`jotain-line-numbers-in-prog' toggle so users can flip it off
without editing this file.

### `pixel-scroll` *(built-in / Nix)*

Built-in pixel-precision smooth scrolling. Required for usable
trackpad / smooth-mouse scrolling. \`fast-but-imprecise-scrolling'
lets large jumps skip exact intermediate fontification — a worthwhile
redisplay win on this integrated-GPU Intel machine.

### `hl-line` *(built-in / Nix)*

Built-in current-line highlight — on for code and prose, off
in shells/dired where it would fight the cursor.

### `paren` *(built-in / Nix)*

Built-in matching-paren highlight. Tuned to flash quickly and
highlight even when point is just outside the pair.

### `which-key` *(built-in / Nix)*

Built-in keybinding cheatsheet. After a prefix key, displays a
paged list of completions in the echo area. Discoverability
multiplier — a Jotain staple.

### `calendar` *(built-in / Nix)*

Built-in calendar. Configured for ISO week numbering and a
Monday week start so it agrees with how the rest of Europe
thinks about dates.

### `nerd-icons`

Provides the Nerd-Font glyph alphabet that the rest of the
nerd-icons-\* family draws on. Picks the font family from
`jotain-font-preferences` so the icons match the editor face.

### `nerd-icons-corfu`

Decorates corfu candidates with a kind-specific glyph in the
margin, so completions are scannable at a glance.

### `nerd-icons-completion`

Adds Nerd-Font icons to marginalia annotations (file/buffer
category icons in completion lists).

### `nerd-icons-ibuffer`

Adds Nerd-Font glyphs to ibuffer rows so buffer types are
visually distinguished at a glance.

### `hl-todo`

Highlights TODO / FIXME / HACK / NOTE / XXX keywords in code
with a face that survives theme changes.

### `breadcrumb`

Headerline showing project / file / nested function position —
the missing "where am I in this file?" indicator built on
imenu.

### `pulsar`

Pulses a coloured highlight when point jumps a long distance
(other-window, xref, consult-line). Tells the eye where the
cursor went without staring.

### `rainbow-delimiters`

Colourises matching parens by depth in Lisp buffers — almost
essential for navigating deeply nested forms.

### `indent-bars`

Vertical indent guides for code, treesit-aware so the bars
follow real syntactic indentation. Toggle via
\`jotain-indent-bars-enabled'.

## `init-tabs.el` — Workspace tabs

### `tab-bar` *(built-in / Nix)*

Built-in frame-local tab bar — used as a workspace switcher.
Bar hides itself when only one tab exists, so single-window
sessions are unaffected.

## `init-help.el` — Help system

### `help` *(built-in / Nix)*

Built-in help window. Auto-focus so you can scroll or dismiss
with q/n/p without reaching for the mouse.

### `help-at-pt` *(built-in / Nix)*

Built-in echo-area tooltips on buttons and links when point
lingers — discoverability for the parts of Emacs that aren't
plain text.

### `apropos` *(built-in / Nix)*

Built-in apropos. Bumped to "search everything" so it surfaces
faces, classes, and customs alongside functions and variables.

### `helpful`

Replaces the default describe-\* commands with richer buffers
that include source, callers, examples, and active keybindings
— the single biggest discoverability upgrade in Emacs.

## `init-editing.el` — Editing primitives

### `elec-pair` *(built-in / Nix)*

Auto-insert matching delimiters as you type. Built-in.

### `delsel` *(built-in / Nix)*

When a region is active, typing replaces it instead of leaving
the selection alone. Built-in, on by default in most modern
editors — Emacs needs this opt-in.

### `simple` *(built-in / Nix)*

Two small built-in editing knobs. `kill-region-dwim' makes C-w
with no active region kill a word backwards instead of erroring;
`delete-pair-push-mark' leaves a mark on the former pair contents so
C-x C-x re-selects them. Both are Emacs 31+, guarded so the config
loads on Emacs 30. (The "diff this buffer against its file" action
under `d' during `save-some-buffers' is already built in since Emacs
30, so it needs no config here.)

### `whitespace` *(built-in / Nix)*

Strip trailing whitespace and stray tabs on save without
reformatting the rest of the buffer. Built-in.

### `subword` *(built-in / Nix)*

Treats CamelCase / snake\_case word parts as separate words for
M-f / M-b / M-d. Built-in. Programming-mode only — prose still
gets whole-word motion.

### `newcomment` *(built-in / Nix)*

Defaults for the built-in comment commands (M-;, C-x C-;, M-j).
`comment-multi-line' makes M-j continue inside an open block
comment instead of closing/reopening; `extra-line' style puts
opening and closing delimiters on their own lines for
`comment-region'; `comment-empty-lines' makes `comment-region'
treat blank lines the same as content lines;
`comment-auto-fill-only-comments' keeps automatic line wrapping
(when `auto-fill-mode' is on) confined to comments. C-c ; is an
ergonomic alias for `comment-line' — C-; is taken by embark-dwim.
Per-mode overrides go in the language module via a named hook:
(defun my-foo-mode-setup ()
(setq-local comment-multi-line nil))
(add-hook 'foo-mode-hook #'my-foo-mode-setup)

### `emacs` *(built-in / Nix)*

Bindings for the two transpose commands Emacs ships without
defaults, so the prose-level family (sentence, paragraph) is
reachable alongside the built-in C-t (chars), M-t (words),
C-x C-t (lines), and C-M-t (sexps, tree-sitter aware in Emacs
30+). Caveat: transpose-lines works on real newlines, so it
gives surprising results under visual-line-mode where wrapped
"lines" are visual only.

### `newcomment` *(built-in / Nix)*

Defaults for the built-in comment commands (M-;, C-x C-;, M-j).
`comment-multi-line' makes M-j continue inside an open block
comment instead of closing/reopening; `extra-line' style puts
opening and closing delimiters on their own lines for
`comment-region'; `comment-empty-lines' makes `comment-region'
treat blank lines the same as content lines;
`comment-auto-fill-only-comments' keeps automatic line wrapping
(when `auto-fill-mode' is on) confined to comments. C-c ; is an
ergonomic alias for `comment-line' — C-; is taken by embark-dwim.
Per-mode overrides go in the language module via a named hook:
(defun my-foo-mode-setup ()
(setq-local comment-multi-line nil))
(add-hook 'foo-mode-hook #'my-foo-mode-setup)

### `replace` *(built-in / Nix)*

Emacs 30 ships `replace-regexp-as-diff' and
`multi-file-replace-regexp-as-diff' — run a regex replacement, but
see the result as a unified diff first and either apply it as a
patch or abort. Worth reaching for on any non-trivial refactor.
The dired-marked variant is bound in \`init-navigation.el'.

### `expreg`

Treesit-aware semantic region expansion. Smaller, faster
successor to expand-region; produces better expansions with
much less code now that treesit is everywhere.

### `multiple-cursors`

Visual multi-cursor editing. C-> and C-\< select the next/prev
occurrence; C-c C-\< selects every occurrence in the buffer.

### `vundo`

Visual undo tree on C-x u. Stateless — no .undo-tree side files
cluttering the filesystem like undo-tree.el used to leave
behind.

### `super-save`

Auto-saves buffers when idle and on focus loss, writing the
actual file rather than #foo# auto-save side files. Also strips
trailing whitespace except on the current line so you don't
fight your own cursor.

### `re-builder` *(built-in / Nix)*

Make `M-x re-builder' use string syntax — the same form you'd
paste into `re-search-forward' — instead of the default \`read'
syntax that requires escaping every backslash twice.

## `init-completion.el` — Minibuffer + in-buffer completion

### `minibuffer` *(built-in / Nix)*

Built-in minibuffer customisation: detailed annotations and
historical sorting (Emacs 30) so frequent commands surface first.

### `orderless`

Fuzzy, space-separated, order-independent completion. Pairs with
partial-completion (path globbing) so `/u/s/a` matches
`/usr/share/applications`. The single most important UX win in
the minibuffer.

### `vertico`

Vertical, performant minibuffer completion UI. Replaces the
default `*Completions*` buffer with an inline list. The whole
minibuffer experience hinges on this.

### `vertico-directory` *(built-in / Nix)*

Path-savvy editing in vertico — RET enters a candidate
directory, DEL/M-DEL delete a path component instead of one
character. Bundled with vertico.

### `vertico-multiform` *(built-in / Nix)*

Per-category and per-command display modes (grid for files,
buffer for line/grep so the preview window has room). Bundled
with vertico.

### `vertico-buffer` *(built-in / Nix)*

Lets vertico render in a regular buffer instead of the
minibuffer — used by vertico-multiform for consult-line and the
grep family so candidates have room to breathe.

### `marginalia`

Adds annotation columns (file size, mode, docstring, …) to every
completion list. Pairs with vertico to make minibuffer choices
self-explanatory.

### `consult`

Consult provides preview-as-you-go variants of nearly every
Emacs lookup: buffer switch, line jump, grep, recent files,
imenu, flymake, register store. The big binding table below
replaces a dozen built-ins with a single, consistent UI.

### `embark`

Right-click for the keyboard. C-. on any candidate (file,
symbol, region, command name) opens a menu of actions valid for
that thing. C-h B replaces describe-bindings with a paged view.

### `embark-consult`

Glue between embark and consult — exports a consult result
list (e.g. consult-ripgrep) into a grep buffer with C-c C-o for
the classic search → wgrep refactor flow.

### `avy`

Tree-style char/word/line jumping. Bound under M-g so it sits
next to the goto family. Multi-frame aware.

### `zoxide`

Frecency-ranked directory jump (like the shell zoxide). Adds
visited files automatically; M-g z surfaces the most-recent
matches first.

### `corfu`

In-buffer completion popup — the corfu equivalent of company.
Auto-triggered after 2 chars so it feels like a modern editor
without a long delay.

### `corfu-history` *(built-in / Nix)*

Persists corfu's pick history into savehist so frequent
completions float to the top across sessions. Bundled with
corfu.

### `cape`

Completion-at-point Extensions — extra capf functions (dabbrev,
file path, keyword) that feed corfu when the major mode's own
capf finds nothing useful.

## `init-navigation.el` — dired, project, windows

### `dired` *(built-in / Nix)*

Built-in directory editor — Jotain's primary file manager.
The custom block below tames cross-platform ls quirks (BSD on
macOS lacks `--group-directories-first` and `--dired`). `M-s R`
previews a regex replacement across the contents of all marked
files as a unified diff (Emacs 30's
\`dired-do-replace-regexp-as-diff').

### `dired-x` *(built-in / Nix)*

Built-in dired extras — `dired-omit-mode` hides dotfiles and
cache directories so dired listings show only the things you
actually want to see.

### `dired-async`

Async file ops for dired — wraps `dired-do-copy`, `dired-do-rename`,
`dired-do-symlink`, `dired-do-hardlink` so they fork into a subprocess
instead of blocking the main Emacs. Multi-GB copies no longer freeze
the UI; the mode-line shows progress and a message fires on completion.

### `dired-rsync`

rsync from dired — bound to `C-c C-r` in `dired-mode-map`. Best
for very large transfers or TRAMP sources/destinations: hands marked
files to `rsync` in an async shell buffer with live progress. Uses
`--progress` (not `--info=progress2`) so stock macOS rsync 2.6.9 still
works; noisier output, but portable.

### `ls-lisp` *(built-in / Nix)*

Pure-Lisp ls emulation. Fallback for macOS without GNU coreutils
— gives us folders-first sorting that BSD ls cannot produce.

### `wdired` *(built-in / Nix)*

Built-in writable dired — C-c C-e turns the dired buffer into
a regular text buffer where you can rename/chmod files with the
usual editing commands. Save to commit changes.

### `diredfl`

Pretty colours for dired (font-locks files by type, age,
executability). Pure cosmetic, big readability win.

### `dired-narrow`

Live filter dired buffers by typing a fragment after `/`.
Faster than re-running ls with a glob.

### `dired-subtree`

Inline tree expansion in dired — TAB on a directory expands its
contents below it instead of opening a new buffer.

### `trashed`

Browse the system trash bin from inside Emacs. With
`delete-by-moving-to-trash` set in init-core, every dired
deletion is recoverable through `M-x trashed`.

### `pretty-sha-path`

Shortens `/nix/store/abc123-foo-1.0` to `…foo-1.0` in dired and
shell buffers — purely cosmetic, but transformative on a system
that's mostly Nix store paths.

### `dirvish`

Modern dired front-end with previews, side panels, and miller
columns. Overrides plain dired so every `C-x d` benefits.
`dirvish-side' (C-c D) already provides the docked side-tree that
Emacs 31's new `speedbar-window' offers, so speedbar is intentionally
not wired up here.

### `winner` *(built-in / Nix)*

Built-in window-layout undo/redo — pairs with the toggle helper
below so `C-x 1` becomes a reversible "expand this window"
command.

## `init-vc.el` — Version control

### `vc` *(built-in / Nix)*

Built-in version control. Pinned to Git + Jujutsu — every
other backend is a slow startup tax (probes every visited file's
parents) you almost never benefit from. JJ is supplied by `vc-jj'
below; without it in this list the backend never gets consulted
and project.el won't discover `.jj' roots.

### `vc-git` *(built-in / Nix)*

Quick jump to a file git status reports as changed. Runs
`git status --porcelain=v1 -z -uall' (-z keeps spaces and
non-ASCII paths intact; -uall forces untracked listing
regardless of status.showUntrackedFiles) and offers
M/A/R/C/U/T/?? entries through `completing-read'. Adapted
from Rahul M. Juliato's emacs-solo/switch-git-status-buffer.

### `vc-jj`

Jujutsu (jj) backend for built-in `vc' and `project'. Adds the
JJ entry pinned in `vc-handled-backends' above, so `C-x v …', the
modeline VC state, and `project.el' all light up on jj repos
(typically colocated with git). The jj side wants   [ui]
  diff-formatter = ":git"
  conflict-marker-style = "git"
set via `jj config edit --user' so vc/diff-hl/smerge read jj diffs
and conflicts in the format they expect.

`jotain-switch-jj-status-buffer' (C-x C-j) is the jj twin of the
git status jump above: it parses `jj diff --summary -r @' and offers
the changed files (deletions omitted — the file is gone) through
`completing-read'. The richer interactive view is `majutsu' (C-c j).

### `magit` *(built-in / Nix)*

The Git porcelain. Bound C-x g for status, C-x M-g for global
dispatch, C-c g for the file-specific menu. Refined hunks +
whitespace-ignoring diffs are turned on globally.

### `majutsu` *(built-in / Nix)*

The Jujutsu porcelain — a magit-style interface for jj, sitting
alongside magit (jj is normally colocated with git, so both apply).
C-c j opens the status/log buffer (`majutsu-log', aliased `majutsu');
C-c M-j opens the top-level transient dispatcher. Provided by Nix
(nix/extra-packages.nix), so \`:ensure nil'.

### `magit-todos`

Surfaces TODO/FIXME/HACK comments as a section in magit-status.
Scan depth pinned to 1 so it stays fast on large repos.

### `forge`

PRs, issues, and reviews from GitHub/GitLab/Forgejo inside
magit. Uses the Emacs-30 built-in sqlite so no external
emacsql binary is needed. Auth via \~/.authinfo.gpg
(machine api.github.com login USER^forge password ghp\_…).

### `transient` *(built-in / Nix)*

Built-in transient menu system that magit/forge are built on.
Themed under var/ so its three state files don't drop at the
repo root.

### `diff-hl`

Fringe indicators for added/changed/removed lines in the buffer
you're editing. `diff-hl-flydiff-mode` updates pre-save so the
indicators reflect uncommitted edits, not just the last save.

### `smerge-mode` *(built-in / Nix)*

Built-in conflict-marker editor. Custom prefix C-c ^ groups
upper/lower/next/prev so resolving merges doesn't require
scrolling through the smerge menu.

### `ediff` *(built-in / Nix)*

Built-in interactive diff. Configured with `plain` window setup
so the control panel doesn't pop a separate frame, plus
whitespace-ignoring diffs for less merge noise.

## `init-prog.el` — prog-mode, treesit, eglot

### `prog-mode` *(built-in / Nix)*

Built-in `prog-mode` parent. Just turns on the fill-column
indicator — hl-line and show-paren live in init-ui so they
apply outside programming buffers too.

### `treesit` *(built-in / Nix)*

Built-in tree-sitter substrate. Bumped to font-lock level 4 to
enable every available syntactic decoration.

### `jit-lock` *(built-in / Nix)*

Defer fontification of newly exposed text by a few hundredths of
a second so heavy treesit level-4 font-lock never blocks keystrokes or
scrolling. Pairs with \`redisplay-skip-fontification-on-input' (set in
init-core) — matters more on this slower Intel CPU.

### `treesit-fold`

Code folding driven by treesit syntax nodes — folds along
functions/classes/blocks instead of indentation guesses. Fringe
indicators show fold state.

### `combobulate` *(built-in / Nix)*

Structural editing via treesit (move/clone/raise nodes,
transpose siblings). Heavy enough to be opt-in per buffer via
M-x combobulate-mode or .dir-locals.el. Provided by Nix.

### `eglot` *(built-in / Nix)*

Built-in LSP client. Per-language `eglot-ensure` hooks live
here so all LSP wiring is visible in one place; per-language
mode regexes stay in their `init-lang-*` file. C-c r is the
refactor prefix (rename/format/code-actions).

Beyond the curated hook list, `jotain-prog--maybe-eglot-ensure'
auto-starts eglot for ANY project file whose language server is on the
buffer's (envrc-applied) PATH — so enabling `languages.X.enable' in a
project's devenv lights up its LSP in Emacs with no per-language config.

### `consult-eglot`

Consult-driven workspace symbol search — C-M-. opens an
orderless-filtered list of symbols across the LSP workspace.

### `consult-eglot-embark`

Embark integration for consult-eglot — gives every workspace
symbol an action menu (jump to def, find refs, rename, …).

### `dape`

Debug Adapter Protocol client — the debugging counterpart to
eglot. Ships adapter configs for dlv (Go), debugpy (Python),
codelldb (Rust/C/C++), and more; the adapter binary (e.g. `dlv`)
comes from the project/host PATH, same convention as the LSP
servers. `C-x C-a` is the prefix (the gud convention); stepping
commands carry repeat-maps, so `C-x C-a n n n` keeps stepping.

### `flymake` *(built-in / Nix)*

Built-in inline diagnostic display. Indicator chars (! ? ·) and
end-of-line message rendering keep diagnostics legible without
opening a side window. M-n / M-p navigate.

### `eldoc` *(built-in / Nix)*

Built-in echo-area documentation. Single-line display plus
small idle delay so it feels responsive without flashing while
you type.

### `xref` *(built-in / Nix)*

Built-in cross-reference engine. Pinned to ripgrep (in the
devenv shell) for orders-of-magnitude faster project-wide
lookups than default grep.

### `tagref` *(built-in / Nix)*

Cross-reference checker for `[tag:x]'/`\[ref:x]' directives. Adds
completion, xref navigation (M-. jumps from a ref to its tag, M-? finds
references), and `M-x tagref-check' (clickable compilation buffer).
Needs the `tagref' CLI on PATH (dev shell / Home Manager wrapper).
Provided by Nix (not on MELPA).

### `compile` *(built-in / Nix)*

Built-in compile / recompile. Auto-scroll until the first error
and skip the "save?" prompt — the annoying defaults that make
people reach for projectile or compilation-multi alternatives.

### `editorconfig` *(built-in / Nix)*

Honour `.editorconfig` files (indent style/width, line endings,
trailing whitespace). Built-in since Emacs 30.

### `apheleia`

Async format-on-save through external formatters (ruff, nixfmt,
rustfmt, prettier, …). Replaces hand-rolled per-language hooks
with one place to look. Per-buffer override safe-local-variable
lets `.dir-locals.el` opt out.

### `wgrep`

Edit grep / ripgrep result buffers in place; saving propagates
edits to every matched file. Powers the project-wide refactor
flow: consult-ripgrep → C-c C-o (embark-export) → C-x C-q
(wgrep) → edit → C-c C-c.

### `dtrt-indent`

Detect indentation width from file contents — saves us from
having to special-case every project's tab/space convention.

## `init-project.el` — Per-project commands

### `project` *(built-in / Nix)*

Built-in project tracker. Extra root markers below mean a
project is recognised when any of these is present, not just
on a VCS root. Project list lives under var/. `C-x p P' scans
`jotain-projects-directories' to add+open projects not yet in
the known list.

### `projection`

`.dir-locals.el`-driven per-project commands (configure, build,
test, run, package, install) auto-detected from
Makefile/justfile/Cargo.toml/etc and exposed under C-x P.

### `projection-multi`

Bridges projection with compile-multi: project-prefix RET picks
from every named compile command available in this project.

### `projection-multi-embark`

Embark menu for projection-multi entries — pin a command,
preview output, etc.

### `compile-multi`

Per-major-mode picker for named compile commands ("go test",
"pytest file", "nix flake check", …). Complement to projection,
kept side by side because neither system fully covers the other.

### `consult-compile-multi`

Renders compile-multi pickers through consult — gives you
orderless filtering and preview on every "what command should I
run?" prompt.

### `compile-multi-nerd-icons`

Decorates compile-multi entries with nerd-font glyphs for the
command type — purely visual, but a useful at-a-glance hint.

### `compile-multi-embark`

Embark actions on compile-multi entries (run, copy, edit
command line). Mirrors the projection embark integration.

## `init-devenv.el` — devenv.sh integration

### `devenv` *(built-in / Nix)*

Native devenv.sh integration (the in-repo `lisp/devenv.el`
library). `C-c v` opens a transient with task and script runners,
`devenv test`/`build` through compilation-mode with Nix error
matching, a process-manager dashboard (start/stop/restart/logs),
and environment introspection (`devenv eval`/`info`/`search`).
`devenv-reload` refreshes the project environment through envrc
(the direnv substrate configured in init-prog) and offers to
reconnect eglot servers so they see the new environment.
devenv.nix buffers are routed to the bundled `devenv lsp` server
while `nil` keeps serving other Nix files, and `devenv-mcp-setup`
registers the project's `devenv mcp` server with mcp.el so gptel
can call its tools. `devenv-allow`/`devenv-revoke` manage devenv
2.1's auto-activation trust database, which also gates the native
env loader, and `devenv-modeline-mode` (enabled here) shows the
per-buffer status — devenv\[on]/\[off]/\[!] — in the mode line.
Everything degrades to a clean error when the `devenv` binary is
not on PATH.

## `init-ai.el` — AI assistants

### `claude-code-ide` *(built-in / Nix)*

Agentic multi-file editing through the Claude Code CLI. Bound to
C-c C-' so the menu is one key away whenever a refactor needs more
context than a single LSP rename can carry. Provided by Nix
(manzaltu/claude-code-ide.el is not on MELPA).

### `eca`

Editor Code Assistant — AI pair-programming client (chat, inline
completion, rewrite, MCP) talking to an external \`eca' server over
JSONRPC. The server binary is provided by Nix and found on \$PATH, so
nothing is downloaded; provider keys come from the environment, same as
gptel. C-c C-e starts a session and opens the chat.

### `gptel`

Conversational LLM front-end with multiple backends. OpenRouter
— an OpenAI-compatible aggregator fronting Claude, GPT, Gemini,
DeepSeek, Qwen, GLM and more behind one key — is the default; direct
Anthropic, Gemini and local Ollama backends stay selectable from the
C-c M-RET menu. Bound to C-c RET / C-c M-RET for quick send and full
menu. Keys come from the environment first, then auth-source via
auth-source-1password.

### `mcp`

Model Context Protocol bridge — lets gptel call MCP tools so the
LLM can read files, query databases, and act through registered
servers. Loaded after gptel.

## `init-shell.el` — Shells

### `eshell` *(built-in / Nix)*

Built-in Lisp-driven shell — works the same on every platform
and is the right tool for Emacs-flavoured pipelines (commands
as Elisp functions, no subprocess for builtins).

### `comint` *(built-in / Nix)*

Built-in REPL substrate (used by python, ielm, sql, etc.).
The settings here apply to every comint-derived buffer.

### `ielm` *(built-in / Nix)*

Built-in Emacs Lisp REPL. Emacs 31+ can persist input history
across sessions like comint/shell already do; point it at a file
under \`var/'. Guarded so the config loads on Emacs 30.

## `init-terminal.el` — Terminal support

### `ghostel`

Terminal emulator powered by libghostty-vt (the Ghostty VT
engine) via a native dynamic module.  Replaces vterm: real PTY for
tmux/ncurses/TUI programs, plus shell integration (OSC 7 directory
tracking, OSC 133 prompt jumping) injected automatically for
bash/zsh/fish.  The Nix package builds the module from source and
ships it in the package directory; in a source checkout the module
is downloaded into the writable elpa/ dir on first \`M-x ghostel'.

### `kkp`

Kitty Keyboard Protocol — lets terminal Emacs distinguish
C-i/TAB, C-m/RET, C-\[/ESC, and pass Shift-modified function
keys through. No-op in GUI frames, so safe to enable
unconditionally.

### `clipetty`

OSC 52 clipboard integration. Yank/kill in terminal Emacs
reaches the system clipboard even through ssh + tmux.

## `init-systems.el` — Sysadmin tools

### `auth-source-1password`

Pulls credentials from the 1Password CLI (`op`). Once enabled,
every package that uses auth-source — magit/forge, gptel,
smtpmail, circe — resolves credentials by host against the
1Password vault transparently.

### `sops`

Transparent SOPS encrypt/decrypt for YAML/JSON/env files. C-c
C-c saves an encrypted edit; C-c C-d toggles into the editing
view; C-c C-k cancels.

### `logview`

Major mode for log files — level filtering, timestamp parsing,
thread highlighting. Configured for SLF4J (Java/Kotlin) and a
custom ROS2 submode.

## `init-tracking.el` — Activity tracking

### `keyfreq`

Counts command invocations to disk; `M-x keyfreq-show` ranks
the busiest commands so you can spot rebinding opportunities.
Tiny, no daemon, no network.

### `wakatime-mode`

Heartbeats to a Wakatime / Wakapi server. The `:if` guard makes
the whole block a no-op when `wakatime-cli` or
WAKATIME\_API\_KEY is missing, so you can install Wakapi later
without reconfiguring Emacs.

### `activity-watch-mode`

ActivityWatch integration — correlates editor activity with
the rest of the machine. Installed but OFF by default; enable
with `M-x global-activity-watch-mode` once the AW server is
running, or set the option in custom.el to persist.

## `init-writing.el` — Prose & notes

### `text-mode` *(built-in / Nix)*

Built-in text-mode tweaks for prose: visual line wrap and
hanging indent on wrapped lines. Proportional fonts come from
\`mixed-pitch' (below); code modes stay monospaced.

### `mixed-pitch`

Proportional fonts for prose via the `variable-pitch' face,
while code, tables, and verbatim spans stay monospaced
(`fixed-pitch'). This keeps Org tables aligned, where a blanket
\`variable-pitch-mode' would leave them ragged. Enabled in every
text-mode buffer and opted out of the column-sensitive ones: YAML
(see init-lang-data), commit messages, and email.

### `jinx`

Just-in-time spell check using enchant — no on-save scan, no
per-buffer flyspell setup. M-$ corrects the word at point;
C-M-$ switches dictionaries.

### `markdown-mode`

Markdown major mode with native code-block fontification and
heading scaling. README.md opens in gfm-mode for the GitHub
dialect.

### `denote`

Plain-text note system with strict file-naming rules so notes
are findable years later. Stored under `~/Documents/notes`.

### `pdf-tools`

In-Emacs PDF viewing — search, annotate, follow links, outline.
Needs libpoppler at build time, which the emacs-pgtk / emacs-mac
variants in nixpkgs already provide.

## `init-org.el` — Org

### `org` *(built-in / Nix)*

Built-in Org — outline, agenda, capture, literate-programming.
Treated as a "third-party" package despite being built-in
because it's the size and surface area of one. Capture templates
and a small bind table live below.

### `org-clock` *(built-in / Nix)*

Built-in time tracking with persistence across restarts. Lets
you resume an interrupted clock without losing the entry.

### `org-appear`

Reveal Org emphasis markers (`*` `_` `/` `~`) only when point is
on them — best of both visual worlds: clean reading, easy
editing.

### `org-modern`

Modern visual styling for Org buffers and agenda — typographic
bullets, faux-rendered blocks, agenda decorations.

### `org-roam`

Zettelkasten-style note-linking on top of Org. SQLite database
auto-syncs in the background; C-c n f / i / c are the three
bindings you actually use day-to-day.

## `init-lang-nix.el` — Nix

### `nix-ts-mode` *(built-in / Nix)*

Tree-sitter Nix major mode. Nix is the package manager and
dev-shell tool the whole config is built around, so it gets a
dedicated module even though we don't write much of it daily.
Provided by Nix; format-on-save flows through apheleia →
nixfmt (configured in init-prog).

## `init-lang-rust.el` — Rust

### `rust-ts-mode` *(built-in / Nix)*

Built-in tree-sitter Rust mode. Eglot wires rust-analyzer in
init-prog; format-on-save runs rustfmt through apheleia.

## `init-lang-python.el` — Python

### `python` *(built-in / Nix)*

Built-in Python mode pinned to its tree-sitter variant so we
get the modern parser without any third-party package. The LSP
server (pyright/basedpyright/ruff-lsp) comes from the project's
own environment, not from this config.

## `init-lang-go.el` — Go

### `go-ts-mode` *(built-in / Nix)*

Built-in tree-sitter Go modes: `go-ts-mode` for source files,
`go-mod-ts-mode` for go.mod, `go-work-ts-mode` (Emacs 31) for
go.work. Eglot wires gopls in init-prog; format-on-save runs
goimports through apheleia; dape drives dlv for debugging. All Go
tooling (go, gopls, goimports, dlv) comes from the project/host
PATH, not from this config.

### `go-tag`

Struct-tag editing (`json:"..."', `db:"..."', …). gopls has no
equivalent; the underlying `gomodifytags' binary comes from the
project environment. Bound under the buffer-local `C-c C-t' Go
tooling prefix so it never shadows the global \`C-c t' theme toggle.

### `gotest`

Run the Go test or benchmark at point, the current file's
tests, or the whole project, with compilation-mode error jumping.
Complements the project-wide compile-multi "go test" commands with
single-test / single-file runs. Shares the mode-local \`C-c C-t' Go
tooling prefix with go-tag.

## `init-lang-web.el` — Web (TypeScript, JS, CSS, HTML)

### `typescript-ts-mode` *(built-in / Nix)*

Built-in tree-sitter TypeScript / TSX / JSX modes. Eglot wires
typescript-language-server in init-prog.

### `js` *(built-in / Nix)*

Built-in JavaScript major mode pinned to its tree-sitter
variant.

### `css-mode` *(built-in / Nix)*

Built-in CSS / SCSS major mode pinned to the tree-sitter
variant.

### `web-mode`

One mode for every templating language that mixes HTML with
something else: ERB, Mustache, Django, ASP, JSP, PHP. The
M-o rebind below stops web-mode-map from shadowing our global
other-window binding.

## `init-lang-devops.el` — DevOps (CI, IaC, containers)

### `dockerfile-mode`

Dockerfile major mode — syntax highlighting plus build
commands (`M-x dockerfile-build-buffer`). The runtime command
name comes from `jotain-docker-backend`.

### `docker-compose-mode`

YAML-flavoured docker-compose syntax with awareness of compose
keywords and service references.

### `terraform-mode`

HCL-aware Terraform mode for `.tf` files. Loaded by the mode
regex; LSP comes from terraform-ls (configured in init-prog).

### `gitlab-ci-mode`

YAML mode tuned for `.gitlab-ci.yml` keywords — includes,
rules, jobs. Saves a lot of typo'd job names on CI debugging
days.

### `just-mode`

Major mode for `Justfile` — the project-aware command runner
Jotain itself uses. Pairs with compile-multi for project
commands.

### `ansible`

Ansible minor mode layered on top of yaml-mode for playbook
files. Adds module-name completion and Jinja2 highlighting.

### `bazel`

Bazel/Starlark support — major modes for `BUILD`, `WORKSPACE`,
`MODULE.bazel`, `REPO.bazel`, `*.bzl`, `.bazelrc`, `.bazelignore`
and `.bazeliskrc` (auto-mode-alist comes from the package's own
autoloads). `C-c C-f` runs buildifier; format-on-save for the
Starlark-family buffers is wired through apheleia in init-prog.

## `init-lang-data.el` — Data formats

### `yaml-mode`

YAML major mode (MELPA). Loaded on demand for the dozens of
YAML-shaped files in any modern repo (CI, k8s, helm). YAML derives
from `text-mode' upstream, so we re-fire `prog-mode-hook' to get
the full editor surface (line numbers, flymake, indent guides, …).

### `yaml-ts-mode` *(built-in / Nix)*

Built-in tree-sitter YAML mode (Emacs 29+). Same prog-mode
hook tweak as `yaml-mode'; kept in its own use-package block so
users running the built-in mode aren't forced to install the
MELPA `yaml-mode' package by \`use-package-always-ensure'.

### `csv-mode`

CSV major mode with column alignment. csv-align-mode renders
separators visually so wide files become readable without
reflowing the actual bytes.

### `sql-indent`

Smart indentation for SQL files — keeps SELECT lists, JOINs,
and CTEs aligned without manual whitespace fiddling.

### `jinja2-mode`

Jinja2 / Ansible / Saltstack templating syntax. Mode regex
covers `.j2`, `.jinja`, and `.jinja2`.

### `gnuplot`

Major mode for gnuplot script files (`.plt`). Useful when an
analysis pipeline emits its own plotting scripts.

## `init-lang-systems.el` — Systems (C/C++, Haskell, Zig)

### `cc-mode` *(built-in / Nix)*

Built-in C/C++ mode with a Stroustrup style bias. The header
extensions below default to C++ — Jotain assumes that's the
more common case in modern repos.

### `cmake-mode`

CMake mode for CMakeLists.txt and `.cmake` files. Mode regex
covers both file conventions.

### `meson-mode`

Meson mode for `meson.build`, `meson_options.txt`, and
`meson.options` files. Formatting is configured centrally through
apheleia, using the Meson CLI supplied by the dev shell.

### `haskell-mode`

Haskell major mode. Loaded on demand only — keeps the rare
Haskell editing session from costing every Emacs start.

### `zig-ts-mode`

Tree-sitter Zig mode (MELPA). Eglot wires zls in init-prog;
format-on-save runs \`zig fmt' through apheleia.

## `init-snippets.el` — Other

### `tempel`

Lightweight template/snippet engine from the corfu/cape author.
Templates are read from `templates/*.eld' (keyed by major mode);
`M-+' completes a snippet by name, `M-*' inserts one interactively,
and once fields are active `TAB'/\`S-TAB' move between them.

### `eglot-tempel`

Lets Tempel expand the snippets language servers send back
(e.g. function-argument placeholders from rust-analyzer / pyright).
\`eglot-tempel-mode' must be enabled before eglot connects, so it is
armed the moment eglot loads rather than after the first session.