Refactor Emacs config into modules

1 files changed, 81 insertions, 0 deletions

diff --git a/docs/plans/2026-04-09-modular-emacs-architecture-design.md b/docs/plans/2026-04-09-modular-emacs-architecture-design.md
new file mode 100644
index 0000000..1c2ce14
--- /dev/null
+++ b/docs/plans/2026-04-09-modular-emacs-architecture-design.md
@@ -0,0 +1,81 @@
+# Modular Emacs Architecture Design
+
+**Date:** 2026-04-09
+
+## Goal
+
+Refactor the repository from a single literate `config.org` source into a
+hand-edited modular Emacs configuration built around `init.el`,
+`early-init.el`, and a small set of domain-based Lisp modules under `lisp/`,
+while preserving existing behavior as closely as possible.
+
+## Scope
+
+This change is an architectural refactor, not a workflow redesign. Existing
+startup behavior, packages, capture flows, agenda rules, CRM commands,
+completion setup, and keybindings should remain materially the same unless a
+small structural adjustment is required by the new module boundaries.
+
+## Architecture
+
+### Entry points
+
+- `early-init.el` remains a standalone file and contains only true early
+  startup concerns that must exist before the first GUI frame.
+- `init.el` becomes the hand-edited runtime entry point.
+- `init.el` adds `lisp/` to `load-path`, defines a central
+  `ss-enabled-features` list, requires `ss-core`, and conditionally loads and
+  sets up each high-level feature module.
+
+### Module boundaries
+
+- `lisp/ss-core.el`
+  Owns Emacs version checks, package bootstrap, shared constants and helper
+  functions, note-system paths, and small shared editor defaults that other
+  modules depend on.
+- `lisp/ss-ui.el`
+  Owns theme, fonts, frame behavior, modeline, and terminal-versus-GUI UI
+  setup.
+- `lisp/ss-org.el`
+  Owns base Org configuration, shared Org helpers, startup MOC behavior, and
+  note-opening helpers.
+- `lisp/ss-agenda.el`
+  Owns agenda file discovery rules and agenda command setup.
+- `lisp/ss-capture.el`
+  Owns journal capture helpers and `org-capture` templates.
+- `lisp/ss-denote.el`
+  Owns Denote configuration and note creation helpers.
+- `lisp/ss-crm.el`
+  Owns all people CRM logic, including parsing, cache management, abbrevs,
+  CAPF, lookup, open/find/insert/add/report commands, and prompt helpers.
+- `lisp/ss-gptel.el`
+  Owns the experimental `gptel` integration.
+- `lisp/ss-keys.el`
+  Owns central global keybindings only.
+
+### Dependency shape
+
+- `ss-core` is the only unconditional module.
+- Other modules may depend on `ss-core` helpers and shared path constants.
+- `ss-keys` binds commands provided by other modules but should not implement
+  workflow logic itself.
+- Side effects should happen in each module's `ss-...-setup` function rather
+  than during `require`, except for definitions that are harmless at load time.
+
+## Migration decisions
+
+- Remove `config.org` entirely after extraction. There will be no transitional
+  dual system and no compatibility tangling layer.
+- Keep `build` only if it remains useful for the modular setup; otherwise
+  remove or repurpose it truthfully.
+- Keep `reset` only if it still aligns with the hand-edited architecture;
+  update it so it no longer treats `init.el` or `early-init.el` as generated
+  artifacts.
+
+## Validation
+
+- Primary validation: `emacs --batch -Q --load ./init.el`
+- If the refactor preserves terminal-specific UI behavior, also verify in a
+  real `emacs -nw` session when practical.
+- Documentation must be updated in the same change so `README.md` and
+  `AGENTS.md` describe the modular architecture truthfully.