1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
# Emacs Configuration
This repository contains a literate Emacs configuration built around Org mode, Denote, a PARA-style note layout, and a small completion stack. The hand-edited source is `config.org`; `init.el` and `early-init.el` are generated from it.
## Emacs Setup
### Source of truth and generated files
`config.org` is the only file intended for manual configuration edits. The generated startup files are:
- `early-init.el` for settings that must exist before the first GUI frame.
- `init.el` for the main runtime configuration.
Both generated files are tangled from `config.org` and should be treated as build artifacts.
### Package bootstrap
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.
### Core packages and built-in modules
The current setup uses these packages and built-in modules:
- `org` and `org-capture` for agenda, capture, daily notes, and the literate configuration itself.
- `denote` for durable notes, naming, keywords, and linking.
- `vertico` for minibuffer completion UI.
- `orderless` for flexible completion matching.
- `marginalia` for minibuffer annotations.
- `gptel` with the GitHub Copilot backend for chat and rewrite workflows inside Emacs.
- `dired` with a macOS-safe `ls` configuration.
- `time` for the modeline clock.
- `modus-themes`, using `modus-vivendi` in the current config.
### Org mode and note layout
The note system lives under `~/org/` and is organized like this:
- `daily/` for plain daily Org files.
- `projects/` for project notes.
- `areas/` for area notes.
- `areas/people/` for people-related notes.
- `resources/` for reference material.
- `archives/` for archived notes.
This is a PARA-style layout, but the agenda is intentionally narrower than the full tree. Agenda files are discovered dynamically from `projects/`, `areas/`, and `resources/` only. Daily notes and archives are excluded from the agenda scan.
### Completion setup
The minibuffer stack is intentionally small:
- `vertico` provides the completion UI.
- `orderless` handles matching.
- `marginalia` adds annotations.
### Babel tangle process
The literate config uses Org Babel to generate the runtime files. Most Emacs Lisp blocks inherit `:tangle init.el` from the file header, while early-startup blocks explicitly tangle to `early-init.el`.
To regenerate the generated files from the repo root:
```sh
emacs --batch -Q --eval '(progn (require (quote ob-tangle)) (org-babel-tangle-file "config.org"))'
```
To verify that the generated main config still loads:
```sh
emacs --batch -Q --load ./init.el
```
## Workflow
### Daily notes
Daily notes are plain Org files in `~/org/daily/`, named by date. When a daily note is created through the config, it starts with these headings:
- `Tasks`
- `Meetings`
- `Notes`
- `Open loops`
This keeps daily capture fast without routing everything through Denote.
### Agenda usage
The agenda is opened through `ss/open-agenda`, bound to `C-c a`. That command explicitly loads `org-agenda`, and the config refreshes `org-agenda-files` immediately before each `org-agenda` invocation so the agenda sees the current PARA files without relying on a fixed file list.
This means the agenda reflects the current project, area, and resource files at runtime instead of relying on a fixed file list.
### Capture flow
`C-c c` opens capture. The configured templates cover:
- daily tasks
- daily notes
- daily meetings
- Denote-backed captures for generic notes, projects, areas, people, resources, and meetings
Denote captures prompt for title, keywords, and subdirectory placement where appropriate, while daily captures write directly into the current day's plain Org file.
### Note creation and linking
Denote handles long-lived notes. The main bindings are:
- `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 create a PARA subdirectory from the minibuffer before capturing into it.
- `C-c n d` to open today's daily note.
Keyword prompts and directory placement are part of the workflow, not an afterthought. The config is set up so structure is created first, then capture writes into it.
### 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
- Update `config.org` first, then regenerate `init.el` and `early-init.el`.
- Keep this README aligned with the current configuration. If package usage, startup behavior, keybindings, or workflow changes, update this file in the same change.
- Do not document planned behavior as if it already exists.
|
