path: root/config.org

-*- buffer-read-only: t -*-
#+title: Emacs Configuration
#+startup: overview
#+DATE: 2026-03-24T10:00:00+11:00
#+DRAFT: false
#+PROPERTY: header-args:emacs-lisp :results silent :tangle init.el

* Early startup

These settings have to exist before the first GUI frame is created, so they
tangle into =early-init.el=.

#+begin_src emacs-lisp :tangle early-init.el
  ;;; early-init.el --- generated from config.org -*- lexical-binding: t; -*-

  ;;; Commentary:

  ;; This file is generated from config.org. Do not edit it directly.

  ;;; Code:

  (dolist (parameter '((width . 140)
                       (height . 42)))
    (add-to-list 'default-frame-alist parameter)
    (add-to-list 'initial-frame-alist parameter))
#+end_src

* Bootstrapping

This is the start of the main runtime entry point, which tangles into =init.el=.

#+begin_src emacs-lisp
  ;;; init.el --- generated from config.org -*- lexical-binding: t; -*-

  ;;; Commentary:

  ;; This file is generated from config.org. Do not edit it directly.

  ;;; Code:

  (let ((minver "27.1"))
    (when (version< emacs-version minver)
      (error "Your Emacs is too old -- this config requires v%s or higher" minver)))
  (when (version< emacs-version "28.1")
    (message
     (concat
      "Your Emacs is old, and some functionality in this config will be "
      "disabled. Please upgrade if possible.")))
#+end_src

* Shared paths and system identity

These definitions set up the shared paths used by the rest of the
configuration, including the Org directory under =~/org/=.

#+begin_src emacs-lisp
  (defconst *spell-check-support-enabled* nil)
  (defconst *is-a-windows* (memq system-type '(windows-nt ms-dos cygwin)))
  (defconst *is-a-linux* (eq system-type 'gnu/linux))
  (defconst *is-a-mac* (eq system-type 'darwin))

  (provide 'init-paths)

  ;; Keep custom-set-variables out of the main config.
  (setq custom-file (expand-file-name "custom.el" user-emacs-directory))
#+end_src

* Package setup

This section bootstraps packages and defines the archives the rest of the
configuration relies on.

#+begin_src emacs-lisp
  (require 'package)

  (setq package-archives
        (append '(("melpa" . "https://melpa.org/packages/"))
                package-archives)
        package-archive-priorities '(("gnu" . 10)
                                     ("nongnu" . 8)
                                     ("melpa" . 5))
        package-install-upgrade-built-in t
        use-package-always-ensure nil)

  (package-initialize)
  (require 'use-package)
#+end_src

* Interface defaults

This section sets the visual defaults: theme, fonts, and frame behavior.

#+begin_src emacs-lisp
  (when (display-graphic-p)
    (set-frame-size (selected-frame) 140 42)
    (menu-bar-mode -1)
    (tool-bar-mode -1)
    (scroll-bar-mode -1)
    (tooltip-mode -1)
    (set-face-attribute
     'default nil
     :family "JetBrains Mono" :height 140 :weight 'medium)
    (set-face-attribute
     'fixed-pitch nil
     :family "JetBrains Mono" :weight 'medium)
    (set-face-attribute
     'fixed-pitch-serif nil
     :family "JetBrains Mono" :weight 'medium))

  (unless (display-graphic-p)
    (add-hook 'emacs-startup-hook (lambda () (menu-bar-mode -1))))

  (setq inhibit-startup-message t
        inhibit-startup-screen t
        ring-bell-function 'ignore)

  (use-package modus-themes
    :ensure nil
    :no-require t
    :config
    (load-theme 'modus-vivendi t))

  (line-number-mode 1)
  (column-number-mode 1)
  (show-paren-mode 1)

  ;; Disable all fringe indicators
  (setq-default indicate-empty-lines nil)
  (setq-default indicate-buffer-boundaries nil)
  (setq-default fringe-indicator-alist nil)

#+end_src

* Modeline

#+begin_src emacs-lisp
  (use-package time
    :ensure nil
    :config
    ;; Enable 24-hour time display without load average.
    (setq display-time-24hr-format t
          display-time-day-and-date t
          display-time-default-load-average nil)
    (display-time-mode 1))

  ;; Keep the theme's faces, but make the right edge alignment dynamic.
  (setq-default mode-line-format
                (list
                 ;; Left padding
                 "  "
                 "%e"
                 mode-line-front-space
                 mode-line-mule-info
                 mode-line-client
                 mode-line-modified
                 mode-line-remote
                 mode-line-frame-identification
                 mode-line-buffer-identification
                 "   "
                 mode-line-position
                 '(vc-mode vc-mode)
                 "  "
                 mode-line-modes
                 ;; Right-align from here
                 '(:eval (propertize
                          " "
                          'display
                          `((space :align-to
                                   (- right
                                      ,(+ 2 (string-width (format-mode-line mode-line-misc-info))))))))
                 mode-line-misc-info
                 ;; Right padding
                 "  "
                 mode-line-end-spaces))

#+end_src

* Editing defaults

This section covers global editing behavior and a few startup-time tuning
choices.

#+begin_src emacs-lisp
  (require 'abbrev)

  (set-language-environment "UTF-8")
  (set-default-coding-systems 'utf-8)
  (prefer-coding-system 'utf-8)

  (setq abbrev-file-name (expand-file-name "abbrev_defs" user-emacs-directory)
        save-abbrevs 'silently)
  (when (file-exists-p abbrev-file-name)
    (quietly-read-abbrev-file abbrev-file-name))

  (defun ss/enable-prose-abbrev-mode ()
    "Enable abbrev mode in prose buffers.
We keep this mode-local so code buffers stay on their own completion rules."
    (abbrev-mode 1))

  (dolist (hook '(text-mode-hook org-mode-hook))
    (add-hook hook #'ss/enable-prose-abbrev-mode))

  (setq auto-save-default nil
        backup-inhibited t
        echo-keystrokes 0.1
        compilation-ask-about-save nil
        mouse-wheel-scroll-amount '(1 ((shift) . 1))
        mouse-wheel-progressive-speed nil
        mouse-wheel-follow-mouse t
        scroll-step 1
        scroll-conservatively 101
        enable-recursive-minibuffers t
        gc-cons-threshold (* 128 1024 1024)
        read-process-output-max (* 4 1024 1024)
        process-adaptive-read-buffering nil)

  (fset 'yes-or-no-p 'y-or-n-p)
  (global-auto-revert-mode 1)
  (delete-selection-mode 1)

  (setq-default indent-tabs-mode nil
                fill-column 80
                tab-width 2
                indicate-empty-lines t
                sentence-end-double-space nil)

#+end_src

* Dired

On macOS, the system =ls= does not support GNU's =--dired= flag. Keeping
Dired on its built-in path avoids noisy directory listing errors when opening
folders from note helpers.

#+begin_src emacs-lisp
  (use-package dired
    :ensure nil
    :custom
    (dired-use-ls-dired nil))
#+end_src

* Minibuffer completion

Completion stays close to standard Emacs behaviour while improving the
minibuffer prompts used throughout the notes workflow. Vertico provides the
UI, Orderless handles flexible matching, and Marginalia adds lightweight
annotations.

#+begin_src emacs-lisp
  (use-package vertico
    :ensure t
    :pin melpa
    :init
    (vertico-mode 1))

  (use-package orderless
    :ensure t
    :pin melpa
    :custom
    (completion-styles '(orderless basic))
    (completion-category-defaults nil)
    (completion-category-overrides '((file (styles basic partial-completion)))))

  (use-package marginalia
    :ensure t
    :pin melpa
    :after vertico
    :init
    (marginalia-mode 1))

  (use-package corfu
    :ensure t
    :pin gnu
    :init
    ;; Enable Corfu globally so text and Org buffers get in-buffer completion
    ;; popups when a CAPF provides candidates.
    (global-corfu-mode 1))
#+end_src

* Name shortcuts

The name workflow uses fixed abbrev shortcuts for deterministic one-shot
expansions and a structured people roster for searchable metadata. Abbrev
mutates the buffer immediately, while Corfu-backed CAPF completion only
proposes candidates and annotations. The roster file holds the name, role,
engagement, and other lookup fields used by manager-facing searches and
reports.

#+begin_src emacs-lisp
  (defconst ss/name-dictionary-file
    (expand-file-name "name-dictionary.el" user-emacs-directory)
    "Persistent source of truth for name abbrevs and CAPF candidates.")

  (defvar ss/name-dictionary-entries nil
    "Persistent name entries used by abbrev and CAPF.")

  (when (file-exists-p ss/name-dictionary-file)
    (load ss/name-dictionary-file nil t))

  (require 'seq)
  (require 'subr-x)

  (defun ss/name-dictionary--entry-name (entry)
    "Return the canonical name in ENTRY."
    (plist-get entry :name))

  (defun ss/name-dictionary--entry-abbrev (entry)
    "Return the abbrev trigger in ENTRY."
    (plist-get entry :abbrev))

  (defun ss/name-dictionary--entry-aliases (entry)
    "Return alias candidates in ENTRY."
    (plist-get entry :aliases))

  (defun ss/name-dictionary-default-abbrev (name)
    "Suggest a short trigger for NAME."
    (let* ((parts (split-string (string-trim name) "[[:space:]]+" t))
           (first (downcase (substring (car parts) 0 (min 2 (length (car parts))))))
           (last (downcase (substring (car (last parts)) 0 1))))
      (if (> (length parts) 1)
          (concat ";" first last)
        (concat ";" first))))

  (defun ss/name-dictionary-read-aliases (prompt)
    "Read PROMPT and return a cleaned alias list."
    (let ((aliases (mapcar #'string-trim (split-string (read-string prompt) "," t))))
      (seq-filter (lambda (string) (not (string-empty-p string))) aliases)))

  (defvar ss/people-roster--cache nil
    "Cached roster entries loaded from `ss/people-roster-file'.")

  (defvar ss/people-roster--cache-mtime nil
    "Modification time of the cached roster entries.")

  (defun ss/people-roster--org-property-line (key value)
    "Return an Org property line for KEY and VALUE, or the empty string."
    (if (and value (not (string-empty-p value)))
        (format ":%s: %s\n" key value)
      ""))

  (defun ss/people-roster--entry-name (entry)
    "Return the canonical name in ENTRY."
    (plist-get entry :name))

  (defun ss/people-roster--entry-abbrev (entry)
    "Return the abbrev trigger in ENTRY."
    (plist-get entry :abbrev))

  (defun ss/people-roster--entry-aliases (entry)
    "Return alias variants in ENTRY."
    (plist-get entry :aliases))

  (defun ss/people-roster--entry-role (entry)
    "Return the role in ENTRY."
    (plist-get entry :role))

  (defun ss/people-roster--entry-engagement (entry)
    "Return the engagement type in ENTRY."
    (plist-get entry :engagement))

  (defun ss/people-roster--entry-team (entry)
    "Return the team in ENTRY."
    (plist-get entry :team))

  (defun ss/people-roster--entry-employee-time (entry)
    "Return the raw employee time in ENTRY."
    (plist-get entry :employee-time))

  (defun ss/people-roster--entry-manager (entry)
    "Return the manager in ENTRY."
    (plist-get entry :manager))

  (defun ss/people-roster--entry-email (entry)
    "Return the email address in ENTRY."
    (plist-get entry :email))

  (defun ss/people-roster--entry-location (entry)
    "Return the location in ENTRY."
    (plist-get entry :location))

  (defun ss/people-roster--split-values (value)
    "Split VALUE on commas or semicolons and trim each item."
    (when (and value (not (string-empty-p value)))
      (seq-filter
       (lambda (string) (not (string-empty-p string)))
       (mapcar #'string-trim (split-string value "[,;]" t)))))

  (defun ss/people-roster--entry-summary (entry)
    "Return a one-line summary for ENTRY."
    (string-join
     (seq-filter
      (lambda (string) (and string (not (string-empty-p string))))
      (list (ss/people-roster--entry-role entry)
            (ss/people-roster--entry-engagement entry)
            (ss/people-roster--entry-team entry)
            (ss/people-roster--entry-manager entry)))
     " | "))

  (defun ss/people-roster-entry-display (entry)
    "Return a searchable display string for ENTRY."
    (let ((name (ss/people-roster--entry-name entry))
          (summary (ss/people-roster--entry-summary entry)))
      (if (string-empty-p summary)
          name
        (format "%s | %s" name summary))))

  (defun ss/people-roster--entry-by-name (name)
    "Return the roster entry matching NAME or one of its aliases."
    (seq-find
     (lambda (entry)
       (or (string= name (ss/people-roster--entry-name entry))
           (member name (ss/people-roster--entry-aliases entry))))
     (ss/people-roster-entries)))

  (defun ss/people-roster--ensure-file ()
    "Create the roster file when it is missing."
    (make-directory (file-name-directory ss/people-roster-file) t)
    (unless (file-exists-p ss/people-roster-file)
      (with-temp-file ss/people-roster-file
        (insert "#+title: People roster\n\n")))
    ss/people-roster-file)

  (defun ss/people-roster-entries ()
    "Return the structured roster entries from `ss/people-roster-file'."
    (let* ((attributes (and (file-exists-p ss/people-roster-file)
                            (file-attributes ss/people-roster-file)))
           (mtime (and attributes (file-attribute-modification-time attributes))))
      (unless (and ss/people-roster--cache
                   (equal mtime ss/people-roster--cache-mtime))
        (setq ss/people-roster--cache
              (when (file-exists-p ss/people-roster-file)
                (with-temp-buffer
                  (insert-file-contents ss/people-roster-file)
                  (org-mode)
                  (goto-char (point-min))
                  (let (entries)
                    (org-element-map (org-element-parse-buffer) 'headline
                      (lambda (headline)
                        (goto-char (org-element-property :begin headline))
                        (let ((name (or (org-entry-get nil "NAME")
                                        (org-element-property :raw-value headline))))
                          (push (list :name name
                                      :abbrev (org-entry-get nil "ABBREV")
                                      :aliases (ss/people-roster--split-values
                                                (org-entry-get nil "ALIASES"))
                                      :role (org-entry-get nil "ROLE")
                                      :employee-time (org-entry-get nil "EMPLOYEE-TIME")
                                      :engagement (org-entry-get nil "ENGAGEMENT")
                                      :team (org-entry-get nil "TEAM")
                                      :manager (org-entry-get nil "MANAGER")
                                      :email (org-entry-get nil "EMAIL")
                                      :location (org-entry-get nil "LOCATION"))
                                entries))))
                    (nreverse entries))))
              ss/people-roster--cache-mtime mtime))
      ss/people-roster--cache))

  (defun ss/people-roster-reload ()
    "Reload the roster cache and refresh prose buffers."
    (interactive)
    (setq ss/people-roster--cache nil
          ss/people-roster--cache-mtime nil)
    (ss/name-dictionary-refresh-buffers)
    (message "Reloaded people roster"))

  (defun ss/people-roster-canonical-names ()
    "Return the canonical names from the roster."
    (mapcar #'ss/people-roster--entry-name (ss/people-roster-entries)))

  (defun ss/people-roster-completion-candidates ()
    "Return roster names and aliases for completion."
    (delete-dups
     (apply #'append
            (mapcar (lambda (entry)
                      (cons (ss/people-roster--entry-name entry)
                            (ss/people-roster--entry-aliases entry)))
                    (ss/people-roster-entries)))))

  (defun ss/people-roster-entry-display-candidates ()
    "Return searchable completion candidates for the roster."
    (mapcar (lambda (entry)
              (cons (ss/people-roster-entry-display entry) entry))
            (ss/people-roster-entries)))

  (defun ss/people-roster-select-entry (&optional prompt)
    "Select a roster ENTRY using PROMPT."
    (let* ((candidates (ss/people-roster-entry-display-candidates))
           (choice (completing-read (or prompt "Person: ") candidates nil t)))
      (or (cdr (assoc choice candidates))
          (user-error "No roster entry selected"))))

  (defun ss/people-roster-open ()
    "Open the roster file."
    (interactive)
    (find-file (ss/people-roster--ensure-file)))

  (defun ss/people-roster-track-buffer ()
    "Refresh roster caches when the roster file is saved."
    (when (and buffer-file-name
               (string= buffer-file-name ss/people-roster-file))
      (add-hook 'after-save-hook #'ss/people-roster-reload nil t)))

  (defun ss/people-roster-open-entry (entry)
    "Open the roster file, jump to ENTRY, and narrow to its subtree."
    (find-file (ss/people-roster--ensure-file))
    (widen)
    (let ((position (org-find-exact-headline-in-buffer
                     (ss/people-roster--entry-name entry))))
      (unless position
        (user-error "No roster heading for %s" (ss/people-roster--entry-name entry)))
      (goto-char position))
    (org-narrow-to-subtree)
    (org-show-subtree)
    (goto-char (point-max)))

  (defun ss/people-find ()
    "Find and open a roster entry."
    (interactive)
    (ss/people-roster-open-entry
     (ss/people-roster-select-entry "Find person: ")))

  (defun ss/people-roster-insert-summary ()
    "Insert a compact roster summary at point."
    (interactive)
    (let ((entry (ss/people-roster-select-entry "Insert person: ")))
      (insert (ss/people-roster-entry-display entry))))

  (defvar ss/people-roster--capture-name nil
    "Most recent roster name captured through `ss/people-roster-capture-name'.")

  (defun ss/people-roster-read-string (prompt &optional default)
    "Read PROMPT and trim the result."
    (string-trim (read-string prompt nil nil default)))

  (defun ss/people-roster-capture-name ()
    "Read the canonical roster name."
    (or ss/people-roster--capture-name
        (setq ss/people-roster--capture-name
              (ss/people-roster-read-string "Full name: "))))

  (defun ss/people-roster-capture-begin ()
    "Reset cached roster capture state."
    (setq ss/people-roster--capture-name nil)
    "")

  (defun ss/people-roster-capture-abbrev ()
    "Read the roster abbrev trigger."
    (let ((name (or ss/people-roster--capture-name
                    (ss/people-roster-capture-name))))
      (ss/people-roster-read-string
       "Abbrev trigger: "
       (ss/name-dictionary-default-abbrev name))))

  (defun ss/people-roster-capture-aliases ()
    "Read optional alias variants for a roster entry."
    (ss/people-roster-read-string "Aliases (comma-separated, optional): "))

  (defun ss/people-roster-capture-role ()
    "Read the role for a roster entry."
    (ss/people-roster-read-string "Role: "))

  (defun ss/people-roster-capture-engagement ()
    "Read the engagement type for a roster entry."
    (completing-read "Engagement: " '("permanent" "sow" "other") nil t nil nil
                     "permanent"))

  (defun ss/people-roster-capture-team ()
    "Read the team for a roster entry."
    (ss/people-roster-read-string "Team: "))

  (defun ss/people-roster-capture-manager ()
    "Read the manager for a roster entry."
    (ss/people-roster-read-string "Manager: " "You"))

  (defun ss/people-roster-capture-email ()
    "Read the email address for a roster entry."
    (ss/people-roster-read-string "Email: "))

  (defun ss/people-roster-capture-location ()
    "Read the location for a roster entry."
    (ss/people-roster-read-string "Location: "))

  (defun ss/people-roster-report-buffer (title group-fn)
    "Render a grouped roster report into a dedicated buffer."
    (let ((groups
           (sort (seq-group-by
                  (lambda (entry)
                    (let ((value (funcall group-fn entry)))
                      (if (string-empty-p (or value ""))
                          "(none)"
                        value)))
                  (ss/people-roster-entries))
                 (lambda (left right)
                   (string< (car left) (car right))))))
      (with-current-buffer (get-buffer-create "*People Roster*")
        (let ((inhibit-read-only t))
          (erase-buffer)
          (org-mode)
          (insert "#+title: " title "\n\n")
          (dolist (group groups)
            (insert "* " (car group) "\n")
            (dolist (entry (sort (copy-sequence (cdr group))
                                 (lambda (left right)
                                   (string< (ss/people-roster--entry-name left)
                                            (ss/people-roster--entry-name right)))))
              (insert "- " (ss/people-roster-entry-display entry) "\n")))
          (goto-char (point-min))
          (view-mode 1))
        (pop-to-buffer (current-buffer)))))

  (defun ss/people-report-by-engagement ()
    "Show roster entries grouped by engagement."
    (interactive)
    (ss/people-roster-report-buffer
     "People by engagement"
     #'ss/people-roster--entry-engagement))

  (defun ss/people-report-by-role ()
    "Show roster entries grouped by role."
    (interactive)
    (ss/people-roster-report-buffer
     "People by role"
     #'ss/people-roster--entry-role))

  (defun ss/people-report-by-manager ()
    "Show roster entries grouped by manager."
    (interactive)
    (ss/people-roster-report-buffer
     "People by manager"
     #'ss/people-roster--entry-manager))

  (defun ss/name-dictionary-canonical-names ()
    "Return the canonical names from the dictionary and roster."
    (delete-dups
     (append (mapcar #'ss/name-dictionary--entry-name ss/name-dictionary-entries)
             (ss/people-roster-canonical-names))))

  (defun ss/name-dictionary-candidates ()
    "Return all CAPF candidates from the dictionary."
    (delete-dups
     (append
      (apply #'append
             (mapcar (lambda (entry)
                       (cons (ss/name-dictionary--entry-name entry)
                             (ss/name-dictionary--entry-aliases entry)))
                     ss/name-dictionary-entries))
      (ss/people-roster-completion-candidates))))

  (defun ss/name-dictionary-entry-by-name (name)
    "Return the legacy dictionary entry matching NAME or an alias."
    (seq-find
     (lambda (entry)
       (or (string= name (ss/name-dictionary--entry-name entry))
           (member name (ss/name-dictionary--entry-aliases entry))))
     ss/name-dictionary-entries))

  (defun ss/name-entry-by-name (name)
    "Return the matching name entry from the roster or legacy dictionary."
    (or (ss/people-roster--entry-by-name name)
        (ss/name-dictionary-entry-by-name name)))

  (defun ss/name-dictionary-install-abbrevs ()
    "Install name abbrevs into the current buffer."
    (setq-local local-abbrev-table (copy-abbrev-table local-abbrev-table))
    (dolist (entry (append ss/name-dictionary-entries (ss/people-roster-entries)))
      (when-let ((name (or (ss/name-dictionary--entry-name entry)
                           (ss/people-roster--entry-name entry))))
        (let ((abbrev (or (ss/name-dictionary--entry-abbrev entry)
                          (ss/people-roster--entry-abbrev entry))))
          (define-abbrev local-abbrev-table
                         (if (or (null abbrev) (string-empty-p abbrev))
                             (ss/name-dictionary-default-abbrev name)
                           abbrev)
                         name)))))

  (defun ss/name-dictionary-refresh-buffers ()
    "Refresh name abbrevs in every prose buffer."
    (dolist (buffer (buffer-list))
      (with-current-buffer buffer
        (when (and (bound-and-true-p abbrev-mode)
                   (derived-mode-p 'text-mode 'org-mode))
          (ss/name-dictionary-install-abbrevs)))))

  (defun ss/name-dictionary-save ()
    "Write the name dictionary file."
    (let ((print-length nil)
          (print-level nil))
      (with-temp-file ss/name-dictionary-file
        (insert ";; -*- lexical-binding: t; -*-\n")
        (insert ";; Persistent name entries used by abbrev and CAPF.\n\n")
        (insert "(setq ss/name-dictionary-entries\n  '")
        (insert (pp-to-string ss/name-dictionary-entries))
        (insert ")\n"))))

  (defun ss/name-dictionary-reload ()
    "Reload the name dictionary file and refresh prose buffers."
    (interactive)
    (when (file-exists-p ss/name-dictionary-file)
      (load ss/name-dictionary-file nil t))
    (ss/people-roster-reload)
    (message "Reloaded name dictionary"))

  (defun ss/name-dictionary--upsert (entry)
    "Insert or replace ENTRY in `ss/name-dictionary-entries'."
    (setq ss/name-dictionary-entries
          (sort
           (cons entry
                 (seq-remove (lambda (existing)
                               (or (string= (ss/name-dictionary--entry-name existing)
                                            (ss/name-dictionary--entry-name entry))
                                   (string= (ss/name-dictionary--entry-abbrev existing)
                                            (ss/name-dictionary--entry-abbrev entry))))
                             ss/name-dictionary-entries))
           (lambda (left right)
             (string< (ss/name-dictionary--entry-name left)
                      (ss/name-dictionary--entry-name right))))))

  (defun ss/name-dictionary--remove (name)
    "Remove NAME from `ss/name-dictionary-entries'."
    (setq ss/name-dictionary-entries
          (seq-remove (lambda (entry)
                        (string= (ss/name-dictionary--entry-name entry) name))
                      ss/name-dictionary-entries)))

  (defun ss/name-dictionary--save-entry (name abbrev aliases)
    "Persist a name entry and refresh prose buffers."
    (let ((entry (list :name name :abbrev abbrev)))
      (when aliases
        (setq entry (append entry (list :aliases aliases))))
      (ss/name-dictionary--upsert entry)
      (ss/name-dictionary-save)
      (ss/name-dictionary-refresh-buffers)
      (message "Added name: %s" name)))

  (defun ss/name-dictionary-add-name (name abbrev aliases)
    "Add a canonical NAME, ABBREV trigger, and optional ALIASES."
    (interactive
     (let* ((name (read-string "Full name: "))
            (abbrev (string-trim
                     (read-string "Abbrev trigger: "
                                  (ss/name-dictionary-default-abbrev name))))
            (aliases (ss/name-dictionary-read-aliases
                      "Aliases (comma-separated, optional): ")))
       (list name abbrev aliases)))
    (when (string-empty-p abbrev)
      (setq abbrev (ss/name-dictionary-default-abbrev name)))
    (ss/name-dictionary--save-entry name abbrev aliases))

  (defun ss/name-dictionary-add-name-from-region (beg end abbrev aliases)
    "Add the active region as a name entry."
    (interactive
     (if (use-region-p)
         (let* ((name (string-trim
                       (buffer-substring-no-properties
                        (region-beginning) (region-end))))
                (abbrev (string-trim
                         (read-string "Abbrev trigger: "
                                      (ss/name-dictionary-default-abbrev name))))
                (aliases (ss/name-dictionary-read-aliases
                          "Aliases (comma-separated, optional): ")))
           (list (region-beginning) (region-end) abbrev aliases))
       (user-error "Select a name first")))
    (let ((name (string-trim
                 (buffer-substring-no-properties beg end))))
      (when (string-empty-p abbrev)
        (setq abbrev (ss/name-dictionary-default-abbrev name)))
      (ss/name-dictionary--save-entry name abbrev aliases)))

  (defun ss/name-dictionary-remove-name (name)
    "Remove NAME from the persistent dictionary."
    (interactive
     (list (completing-read "Remove name: "
                            (mapcar #'ss/name-dictionary--entry-name
                                    ss/name-dictionary-entries)
                            nil t)))
    (ss/name-dictionary--remove name)
    (ss/name-dictionary-save)
    (ss/name-dictionary-refresh-buffers)
    (message "Removed name: %s" name))

  (defun ss/name-dictionary-open ()
    "Open the persistent name dictionary."
    (interactive)
    (find-file ss/name-dictionary-file))

  (defun ss/name-capf ()
    "Return a name completion candidate set at a word boundary."
    (let ((end (point)))
      (save-excursion
        (skip-syntax-backward "w_")
        (let ((beg (point))
              (candidates (ss/name-dictionary-candidates)))
          (when (and (< beg end) candidates)
            (list beg end candidates
                  :exclusive 'no
                  :annotation-function
                  (lambda (candidate)
                    (when-let ((entry (ss/name-entry-by-name candidate)))
                      (let ((summary
                             (or (ss/people-roster--entry-summary entry)
                                 "")))
                        (when (not (string-empty-p summary))
                          (concat "  " summary)))))))))))

  (defun ss/enable-name-capf ()
    "Add `ss/name-capf' once in prose buffers."
    (unless (memq #'ss/name-capf completion-at-point-functions)
      (add-hook 'completion-at-point-functions #'ss/name-capf nil t)))

  (dolist (hook '(text-mode-hook org-mode-hook))
    (add-hook hook #'ss/enable-name-capf))
  (add-hook 'find-file-hook #'ss/people-roster-track-buffer)
#+end_src

* Notes workflow

The note-taking system remains deliberately small. Daily notes stay as plain
Org files in =~/org/daily/=, while longer-lived notes use Denote inside the
same root directory and rely on links for relationships.

** Org foundations

The Org setup establishes the shared directories, ensures the PARA structure is
present at startup, and provides a small helper for opening today's daily note
with the standard section layout already in place. Agenda views stay focused on
PARA notes, so project, area, and resource files can surface TODOs without
pulling in daily or archived notes. A small directory helper keeps PARA
subdirectories easy to create from the minibuffer before capturing into them.
A curated =moc.org= in the Org root acts as the startup landing page and quick
navigation surface. The config assumes that file already exists and opens it
directly during startup rather than creating it on demand.

#+begin_src emacs-lisp
  (use-package org
    :ensure nil
    :functions (denote-keywords-prompt)
    :defines (denote-directory denote-use-directory denote-use-keywords)
    :preface
    (defconst ss/org-directory (expand-file-name "~/org/")
      "Root directory for Org files.")

    (defconst ss/org-daily-directory (expand-file-name "daily/" ss/org-directory)
      "Directory for plain daily Org notes.")

    (defconst ss/org-projects-directory (expand-file-name "projects/" ss/org-directory)
      "Directory for project notes.")

    (defconst ss/org-areas-directory (expand-file-name "areas/" ss/org-directory)
      "Directory for area notes.")

    (defconst ss/org-people-directory (expand-file-name "areas/people/" ss/org-directory)
      "Directory for people notes.")

    (defconst ss/people-roster-file
      (expand-file-name "areas/people/roster.org" ss/org-directory)
      "Structured roster of people and role metadata.")

    (defconst ss/org-resources-directory (expand-file-name "resources/" ss/org-directory)
      "Directory for resource notes.")

    (defconst ss/org-archives-directory (expand-file-name "archives/" ss/org-directory)
      "Directory for archived notes.")

    (defconst ss/moc-file (expand-file-name "moc.org" ss/org-directory)
      "Central MOC note.")

    (defconst ss/org-note-directories
      (list ss/org-directory
            ss/org-daily-directory
            ss/org-projects-directory
            ss/org-areas-directory
            ss/org-people-directory
            ss/org-resources-directory
            ss/org-archives-directory)
      "Directories that make up the note-taking workflow.")

    (defconst ss/org-agenda-directories
      (list ss/org-projects-directory
            ss/org-areas-directory)
      "Directories whose Org files feed the agenda.")

    (defconst ss/org-subdirectory-roots
      `(("projects" . ,ss/org-projects-directory)
        ("areas" . ,ss/org-areas-directory)
        ("people" . ,ss/org-people-directory)
        ("resources" . ,ss/org-resources-directory))
      "Capture roots offered when creating note subdirectories.")

    (defun ss/denote-capture-in-directory (directory &optional keywords &rest prompts)
      "Start a Denote Org capture in DIRECTORY with KEYWORDS and PROMPTS.
  If PROMPTS is empty, rely on `denote-prompts'."
      (let* ((prompt-for-keywords (memq :keywords prompts))
             (denote-directory directory)
             (denote-use-directory (unless (memq :subdirectory prompts) directory))
             (denote-use-keywords
              (if prompt-for-keywords
                  (delete-dups (append keywords (denote-keywords-prompt)))
                keywords)))
        (if prompts
            (denote-org-capture-with-prompts
             (memq :title prompts)
             nil
             (memq :subdirectory prompts)
             (memq :date prompts)
             (memq :template prompts))
          (denote-org-capture))))

    (defun ss/create-note-subdirectory ()
      "Create a PARA subdirectory using minibuffer completion."
      (interactive)
      (let* ((root-name (completing-read
                         "Capture root: "
                         (mapcar #'car ss/org-subdirectory-roots)
                         nil t))
             (root (alist-get root-name ss/org-subdirectory-roots nil nil #'string=))
             (completion-extra-properties '(:category file))
             (candidates
              (sort
               (delete-dups
                (mapcar (lambda (path)
                          (directory-file-name (file-relative-name path root)))
                        (seq-filter
                         #'file-directory-p
                         (directory-files-recursively root directory-files-no-dot-files-regexp t t))))
               #'string<))
             (subdirectory (completing-read
                            (format "Subdirectory in %s: " root-name)
                            candidates
                            nil nil))
             (target (expand-file-name subdirectory root))
             (existing (file-directory-p target)))
        (make-directory target t)
        (ss/refresh-org-agenda-files)
        (message "%s note directory: %s"
                 (if existing "Using existing" "Created")
                 target)))

    (defun ss/refresh-org-agenda-files (&rest _)
      "Refresh `org-agenda-files' from the current PARA directories.
  Ignore any arguments passed by advice wrappers."
      (require 'org-agenda)
      (setq org-agenda-files
            (delete-dups
             (apply #'append
                    (mapcar (lambda (directory)
                              (if (file-directory-p directory)
                                  (directory-files-recursively directory org-agenda-file-regexp)
                                nil))
                            ss/org-agenda-directories)))))

    (defun ss/ensure-daily-note (&optional time)
      "Create the daily note for TIME when it does not exist.
  Return the path to the note."
      (let* ((date (or time (current-time)))
             (file (expand-file-name
                    (format-time-string "%Y-%m-%d.org" date)
                    ss/org-daily-directory)))
        (unless (file-exists-p file)
          (make-directory (file-name-directory file) t)
          (with-temp-file file
            (insert (format "#+title: %s\n\n* Tasks\n\n* Notes\n\n* Open Loops\n"
                            (format-time-string "%Y-%m-%d" date)))))
        file))

    (defun ss/open-todays-note ()
      "Open today's daily Org note."
      (interactive)
      (find-file (ss/ensure-daily-note)))

    (defun ss/open-moc ()
      "Open the central MOC note."
      (interactive)
      (find-file ss/moc-file))

    (defun ss/open-agenda ()
      "Refresh agenda files and invoke `org-agenda'."
      (interactive)
      (call-interactively #'org-agenda))
    :init
    (add-hook 'emacs-startup-hook (lambda () (find-file ss/moc-file)))
    :bind (("C-c a" . ss/open-agenda)
           ("C-c c" . org-capture)
           ("C-c n M" . ss/open-moc)
           ("C-c n f" . ss/people-find)
           ("C-c n m" . ss/create-note-subdirectory)
           ("C-c n d" . ss/open-todays-note)
           ("C-c n r" . ss/people-roster-open))
    :config
    (setq org-directory ss/org-directory
          org-hide-emphasis-markers t)
    (add-hook 'org-mode-hook
              (lambda ()
                (setq-local org-hide-emphasis-markers t)
                (font-lock-flush)
                (font-lock-ensure)))
    (ss/refresh-org-agenda-files)
    (advice-add 'org-agenda :before #'ss/refresh-org-agenda-files)
    (mapc (lambda (directory)
            (make-directory directory t))
          ss/org-note-directories))
#+end_src

** Capture entry points

Daily capture goes to today's plain Org file. Tasks land under =Tasks= while
notes and meetings land under =Notes=. Denote capture uses Denote's own Org
integration so note identity, metadata, and directories stay under Denote's
control rather than custom code. The convenience templates keep the familiar
entry points, but only project capture injects a structural keyword by default.
People have two paths: =nP= creates a Denote note for narrative context, while
=nR= writes a structured roster entry with role and engagement metadata.

#+begin_src emacs-lisp
  (use-package org-capture
    :ensure nil
    :after (org denote)
    :config
    (setq org-capture-templates
          `(("d" "Daily")
            ("dt" "Task" entry
             (file+headline ,#'ss/ensure-daily-note "Tasks")
             "* TODO %?")
            ("dn" "Note" entry
             (file+headline ,#'ss/ensure-daily-note "Notes")
             "* %?")
            ("dm" "Meeting" entry
             (file+headline ,#'ss/ensure-daily-note "Notes")
             "* %<%H:%M> meeting %?")
            ("n" "Denote")
            ("nn" "Generic" plain
             (file denote-last-path)
             (function
              (lambda ()
                (denote-org-capture-with-prompts :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("np" "Project" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-projects-directory '("project") :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("na" "Area" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-areas-directory nil :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("nP" "Person" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-people-directory nil :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("nR" "Roster" entry
             (file ,#'ss/people-roster--ensure-file)
             "%(ss/people-roster-capture-begin)* %(ss/people-roster-capture-name)\n:PROPERTIES:\n:NAME: %(ss/people-roster-capture-name)\n:ABBREV: %(ss/people-roster-capture-abbrev)\n:ALIASES: %(ss/people-roster-capture-aliases)\n:ROLE: %(ss/people-roster-capture-role)\n:ENGAGEMENT: %(ss/people-roster-capture-engagement)\n:TEAM: %(ss/people-roster-capture-team)\n:MANAGER: %(ss/people-roster-capture-manager)\n:EMAIL: %(ss/people-roster-capture-email)\n:LOCATION: %(ss/people-roster-capture-location)\n:END:\n%?"
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t)
            ("nr" "Resource" plain
             (file denote-last-path)
             (function
              (lambda ()
                (ss/denote-capture-in-directory
                 ss/org-resources-directory nil :title :keywords :subdirectory)))
             :no-save t
             :immediate-finish nil
             :kill-buffer t
             :jump-to-captured t))))
    (add-hook 'org-capture-after-finalize-hook #'ss/people-roster-reload)
#+end_src

** Denote

Denote manages the durable notes. Folder placement carries most of the
structural meaning, while Denote handles naming, metadata, linking, and
retrieval. Built-in keywords stay intentionally sparse, with =project=
retained because project note titles are often ambiguous outside their folder.

#+begin_src emacs-lisp
  (use-package denote
    :ensure t
    :after org
    :bind (("C-c n n" . denote-open-or-create)
           ("C-c n l" . denote-link))
    :config
    (setq denote-directory ss/org-directory
          denote-known-keywords '("project")
          denote-prompts '(title keywords)
          denote-org-capture-specifiers "%?")
    (denote-rename-buffer-mode 1))
#+end_src

** Automatic git commits

The notes tree can enable =git-auto-commit-mode= through a =.dir-locals.el=
at =~/org/=. The Emacs config keeps the package available and sets the
machine-specific shell command chaining based on the active shell, while the
repo-local behavior lives with the notes tree.

#+begin_src emacs-lisp
  (use-package git-auto-commit-mode
    :ensure t
    :pin melpa
    :commands (git-auto-commit-mode)
    :init
    (setq gac-shell-and
          (if (string-match-p "fish\\'" shell-file-name)
              " ; and "
            " && ")))
#+end_src

* Gptel workflow

LLM chat remains a small workflow tool inside Emacs. GitHub Copilot
authentication is handled on demand by gptel, so there is no token plumbing in
this file.

#+begin_src emacs-lisp
  (use-package gptel
    :ensure t
    :init
    (setq gptel-default-mode 'org-mode
          gptel-model 'gpt-4o
          gptel-backend (gptel-make-gh-copilot "Copilot"))
    :bind (("C-c n g" . gptel)
           ("C-c n s" . gptel-send)
           ("C-c n r" . gptel-rewrite)
           ("C-c n a" . gptel-add)))
#+end_src

* Generated file footers

The closing blocks just finish the generated startup files cleanly.

#+begin_src emacs-lisp

  (when (file-exists-p custom-file)
    (load custom-file nil 'nomessage))

  ;;; init.el ends here
#+end_src

#+begin_src emacs-lisp :tangle early-init.el

  ;;; early-init.el ends here
#+end_src