# Emacs Configuration This repository contains a modular Emacs configuration built around Org mode, Denote, a PARA-style note layout, a people CRM, and a small completion stack. `init.el` is the hand-edited entry point, `early-init.el` handles true early startup concerns, and the runtime implementation is hand-edited across the domain modules under `lisp/`. ## System Model This repository configures Emacs. It does not define, create, or validate the `~/org` note system. - `init.el` is the source of truth for runtime composition and feature selection. - `early-init.el` is the source of truth for true early startup settings. - `lisp/ss-*.el` is the source of truth for the runtime implementation by domain. - `~/org` is external to this repository and must already exist. - The configuration may open files in `~/org`, but it must not create directories, create files, or validate note structure. - `~/org/journal.org` is the operational journal. It must already exist, and the configuration may open it but must not create or manage it. - `~/org/moc.org` is a normal note. It must already exist, and the configuration may open it but must not create or manage it. - `~/org/areas/people/people.org` is the people CRM file. It must already exist, and the configuration may open it but must not create or manage it. - PARA is the organising model for durable notes. Folder placement carries meaning, and workflows must respect that placement. ## Repository Layout The runtime architecture is: ```text early-init.el init.el lisp/ ss-core.el ss-ui.el ss-org.el ss-agenda.el ss-capture.el ss-denote.el ss-crm.el ss-gptel.el ss-keys.el ``` The module responsibilities are: - `ss-core.el` bootstraps packages, defines shared paths and helpers, and applies shared editor defaults. - `ss-ui.el` owns theme, fonts, frame behavior, modeline, and completion UI. - `ss-org.el` owns base Org setup, startup MOC behavior, and shared note helpers. - `ss-agenda.el` owns agenda discovery and agenda commands. - `ss-capture.el` owns journal capture structure and capture templates. - `ss-denote.el` owns Denote setup and durable-note capture helpers. - `ss-crm.el` owns all people CRM behavior. - `ss-gptel.el` owns the experimental GitHub Copilot-backed `gptel` setup. - `ss-keys.el` owns global keybindings only. `init.el` enables high-level features centrally through `ss-enabled-features`. Feature toggling works by including or excluding a module there. ## Package Model The config bootstraps packages with built-in `package.el` and uses `use-package` for declaration and load order. Package archives are configured with GNU, NonGNU ELPA, and MELPA, with GNU given highest priority. The current setup uses: - `org` and `org-capture` for agenda and journal capture - `denote` for durable notes, naming, keywords, and linking - `git-auto-commit-mode` for optional automatic commits inside `~/org` when enabled by directory-local settings - `vertico` for minibuffer completion UI - `orderless` for flexible completion matching - `marginalia` for minibuffer annotations - `corfu` for in-buffer completion popups in text and Org buffers - `gptel` with the GitHub Copilot backend as an experimental tool - `dired` with a macOS-safe `ls` configuration - `time` for the modeline clock - `modus-themes`, using `modus-vivendi` ## Org Layout The note system lives under `~/org/` and is organised like this: - `journal.org` for the operational journal - `daily/` for older daily Org files that may still exist - `projects/` for project notes - `areas/` for area notes - `areas/people/people.org` for the people CRM - `resources/` for reference material - `archives/` for archived notes Agenda discovery is rule-based: - include `~/org/journal.org` - recursively scan `.org` files under `~/org/projects/`, `~/org/areas/`, and `~/org/resources/` - exclude `~/org/archives/` ## People CRM The people workflow is a CRM rooted at `~/org/areas/people/people.org`. - each top-level heading represents one person - entries are structured around heading text and flat properties - the system rebuilds people abbrevs from the CRM file - a CAPF provides canonical-name completion while alias matching remains available for lookup - Marginalia annotates people with `role | team | engagement | current focus` - reports are available by role, team, manager, engagement, supplier, and location - `TEAM` captures the current working team and `MANAGER` captures the formal organisational manager - person cards use `ROLE`, `TEAM`, `MANAGER`, `ENGAGEMENT`, `SUPPLIER`, `LOCATION`, and `CURRENT_FOCUS` in that order The CRM commands are: - `M-x ss-crm-open` - `M-x ss-crm-overview` - `M-x ss-crm-find` - `M-x ss-crm-insert-name` - `M-x ss-crm-insert-summary` - `M-x ss-crm-add` - `M-x ss-crm-report-by-role` - `M-x ss-crm-report-by-team` - `M-x ss-crm-report-by-manager` - `M-x ss-crm-report-by-engagement` - `M-x ss-crm-report-by-supplier` - `M-x ss-crm-report-by-location` Persistent abbrevs live in `abbrev_defs` at the repository root. The config loads that file on startup, enables abbrev mode only in text-like buffers, and saves learned abbrevs back to the same file silently when buffers are saved. People-specific abbrevs are rebuilt from `~/org/areas/people/people.org` whenever that file changes. ## Workflow `~/org/moc.org` is a normal note. It is treated as a curated navigation note, not a generated system file. The config may open it on startup, and `C-c n M` opens it manually. The capture model has two distinct paths: - fast operational capture goes to `~/org/journal.org` - durable notes use Denote in the PARA directories under `~/org/` Journal capture uses a Year -> Day outline in `journal.org` with explicit `Tasks`, `Notes`, and `Meetings` headings beneath each day entry. The configured capture templates cover: - journal tasks - journal notes - journal meetings - Denote-backed captures for generic notes, projects, areas, and resources The people CRM remains outside `org-capture`: `M-x ss-crm-add` writes directly to `~/org/areas/people/people.org`. ## Keybindings The main bindings are: - `C-c a` for the agenda - `C-c c` for capture - `C-c n n` to open or create a Denote note - `C-c n l` to insert a Denote link - `C-c n M` to open the MOC - `C-c n d` to open `~/org/journal.org` - `C-c n p` to open the people CRM - `C-c n P` to add a new person card - `C-c n f` to find a person card - `C-c n i` to insert a canonical person name - `C-c n I` to insert a compact person summary - `C-c n o` to restore the people overview - `C-c n O` to show people grouped by role - `C-c n T` to show people grouped by team - `C-c n R` to show people grouped by manager - `C-c n E` to show people grouped by engagement - `C-c n S` to show people grouped by supplier - `C-c n L` to show people grouped by location - `C-c n g` to start `gptel` - `C-c n s` to send in `gptel` - `C-c n r` to rewrite with `gptel` - `C-c n a` to add context in `gptel` ## Automatic Note Commits The configuration provides `git-auto-commit-mode` capability. Behaviour is defined in `~/org/.dir-locals.el`. When enabled in `~/org/.dir-locals.el`, saving a file in `~/org/` makes Emacs try to commit that change. The Emacs config supplies the package and selects the shell command separator based on the active shell, while the note tree defines add, push, debounce, and commit-message behavior. Place this file at `~/org/.dir-locals.el`: ```emacs-lisp ((nil . ((eval . (progn (setq-local gac-automatically-add-new-files-p t gac-automatically-push-p t gac-debounce-interval 60 gac-default-message (lambda (_filename) (format-time-string "Auto-commit: %Y-%m-%d %H:%M:%S"))) (git-auto-commit-mode 1)))))) ``` ## Validation The primary verification command for the runtime path is: ```sh emacs --batch -Q --load ./init.el ``` `early-init.el` and `init.el` are hand-edited source files, not generated artifacts. ## Terminal and GUI Behavior GUI Emacs and terminal Emacs are handled slightly differently. - GUI frames get the preferred frame size, font setup, and UI trimming. - In `emacs -nw`, the menu bar is disabled on `emacs-startup-hook` rather than earlier in startup, because changing that timing too early caused interactive terminal regressions in kitty. If you change terminal behavior, test it in a real `emacs -nw` session. Batch load checks are necessary, but they are not enough for tty input and UI behavior. ## Maintenance Rules - Edit `init.el`, `early-init.el`, and `lisp/ss-*.el` directly. - Keep this README aligned with the current configuration. - Keep `README.md` and `AGENTS.md` in sync. - Do not document planned behavior as if it already exists.