diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | README.org | 145 | ||||
| -rw-r--r-- | Workflow.org | 253 |
3 files changed, 400 insertions, 0 deletions
@@ -3,6 +3,8 @@ !/.gitignore !/AGENTS.md !/README.md +!/README.org +!/Workflow.org !/early-init.el !/init.el !/custom.el diff --git a/README.org b/README.org new file mode 100644 index 0000000..a3f8b95 --- /dev/null +++ b/README.org @@ -0,0 +1,145 @@ +#+title: Emacs Org Workflow Configuration + +* Overview + +This repository is a compact Emacs 30 configuration centered on Org mode. +The configuration is intentionally small and keeps the live behavior in two files: + +- =early-init.el= for true early-startup behavior +- =init.el= for runtime configuration and workflow behavior + +Custom-generated settings are kept in =custom.el= so the main configuration stays readable. + +* Implementation Summary + +** Early Startup + +=early-init.el= handles only startup concerns that must run before normal initialization: + +- disables automatic package activation +- removes menu, tool, and scroll bars early to reduce flicker +- increases GC limits during startup +- sets the initial frame font and frame size + +The steady-state GC threshold is restored in =init.el=. + +** Runtime Configuration + +=init.el= is organized into a few direct sections rather than abstractions: + +- core paths +- startup behavior +- package bootstrap +- UI defaults +- completion +- Org configuration +- capture templates + +The configuration prefers built-in Emacs and Org features where possible. + +** Package Management + +Packages are initialized with the built-in package manager. +The configuration installs these packages when missing: + +- =vertico= +- =marginalia= +- =orderless= +- =consult= +- =modus-themes= +- =olivetti= +- =git-auto-commit-mode= + +Archive refresh only happens when a required package is missing. + +** Startup Behavior + +Emacs starts in the custom Org Home agenda. +The startup path explicitly requires =org-agenda= before evaluating =initial-buffer-choice= so the agenda command is available reliably at startup. + +The Home agenda is intended to act like a modal entry point into the workflow. + +** UI and Editor Defaults + +The configuration applies a small set of editor defaults directly: + +- no auto-save files or backup files +- fast minibuffer echoing +- recursive minibuffers enabled +- conservative scrolling +- mouse wheel scrolling tuned for line-by-line movement +- automatic revert of changed files +- active-region replacement via =delete-selection-mode= +- =y-or-n-p= in place of =yes-or-no-p= +- spaces instead of tabs by default +- =fill-column= set to 80 + +The selected GUI frame reapplies the startup font from =default-frame-alist=. + +** Completion Stack + +The minibuffer completion setup is simple and modern: + +- =vertico= provides the UI +- =marginalia= adds annotations +- =orderless= provides matching behavior +- =consult= provides search and outline commands + +** Org Workflow + +The Org setup is organized around a heading-based workflow in a single notes file under =~/org=. +Key behaviors include: + +- Home agenda command on startup +- full-frame agenda display +- stock Org speed commands enabled +- overview startup folding for Org buffers +- drawers hidden at startup +- file-based refile paths with single-step completion +- refile targets limited to agenda files up to level 2 +- internal heading links instead of ID-based links +- heading-respecting insertion and movement behavior + +** Capture Templates + +The capture system stays low-friction and writes into named headings in the default notes file. + +Available templates: + +- Inbox +- Task +- Question +- Meeting +- Recurring + +Inbox, Task, Question, and Recurring entries record a =CAPTURED= property and capture context with =%a=. +Meeting capture remains timestamp-based. + +** Agenda Design + +The Home agenda is ordered as: + +- weekly agenda section +- task list +- open questions +- refile queue + +The refile queue is based on entries under an Inbox subtree that inherits =CATEGORY: inbox=. + +* Files + +** =early-init.el= + +Early startup configuration only. + +** =init.el= + +Main configuration and workflow behavior. + +** =custom.el= + +Custom-generated state loaded at the end of =init.el= so Customize values override defaults. + +** =Workflow.org= + +Human-facing documentation for the workflows and keybindings enabled by this configuration. diff --git a/Workflow.org b/Workflow.org new file mode 100644 index 0000000..25405b3 --- /dev/null +++ b/Workflow.org @@ -0,0 +1,253 @@ +#+title: Workflow Guide + +* Purpose + +This document describes the workflows implemented by this Emacs configuration and the keybindings that support them. +It focuses on the actual behavior configured in this repository. + +* Operating Model + +** Startup + +When Emacs starts, it opens the custom Org Home agenda. +That agenda is the main entry point into the system. + +** Agenda Mode + +Opening the agenda uses a full-frame modal view. +The agenda is intended to become the active workspace rather than appear in a side split. + +** Capture Mode + +Capture reuses the current window and then deletes other windows while capture is active. +The result is a modal capture flow with minimal window churn. + +** Org Buffer Defaults + +When an Org buffer opens: + +- it starts folded to overview level +- drawers are hidden at startup +- standard Org speed commands are enabled + +* Home Agenda + +The Home agenda command key is =h= inside =org-agenda= custom commands. +Its sections appear in this order: + +1. weekly agenda +2. task list +3. open questions +4. refile + +The refile section uses this matcher: + +#+begin_src emacs-lisp +CATEGORY="inbox"+LEVEL>1 +#+end_src + +That means entries under an Inbox subtree can appear in the refile section when the parent heading carries =CATEGORY: inbox=. + +* Capture Workflows + +** Inbox Capture + +- key: =C-c c= then =i= +- target: =Inbox= +- content: plain note +- metadata: =CAPTURED= property and captured context link + +Use this for raw notes that still need sorting or refiling. + +** Task Capture + +- key: =C-c c= then =t= +- target: =Tasks= +- content: =TODO= +- metadata: =CAPTURED= property and captured context link + +** Question Capture + +- key: =C-c c= then =q= +- target: =Questions= +- content: =CLARIFY= +- metadata: =CAPTURED= property and captured context link + +** Meeting Capture + +- key: =C-c c= then =m= +- target: =Meetings= +- content: timestamped meeting note +- metadata: no =CAPTURED= property + +** Recurring Capture + +- key: =C-c c= then =r= +- target: =Recurring= +- content: scheduled =TODO= +- metadata: =CAPTURED= property + +* Refile Workflow + +The configuration is built around using Org refile rather than custom routing. + +Relevant settings: + +- outline paths are file-based +- completion happens in one step +- targets are agenda files up to level 2 + +The intended loop is: + +1. capture into Inbox +2. review the refile section in the Home agenda +3. refile the note into its long-term heading + +* Keybindings + +** Global Commands + +| Key | Command | Purpose | +|-----+---------+---------| +| =C-s= | =consult-line= | Search in the current buffer | +| =C-c o= | =consult-outline= | Jump through headings in the current buffer | +| =C-c c= | =org-capture= | Open capture | +| =C-c a= | =org-agenda= | Open agenda | +| =C-c r= | =org-refile= | Refile current entry | +| =C-c z= | =olivetti-mode= | Toggle focused writing layout | + +** Common Org Commands + +| Key | Command | Purpose | +|-----+---------+---------| +| =C-c C-w= | =org-refile= | Refile subtree | +| =C-c $= | =org-archive-subtree= | Archive subtree directly | +| =C-c C-x C-s= | =org-archive-subtree= | Archive subtree directly | +| =C-c C-x C-a= | =org-archive-subtree-default= | Archive using default archive command | +| =C-c C-l= | =org-insert-link= | Insert link | +| =C-c C-o= | =org-open-at-point= | Open link or reference at point | +| =C-c C-t= | =org-todo= | Change TODO state | +| =C-c C-q= | =org-set-tags-command= | Edit tags | +| =C-c C-s= | =org-schedule= | Schedule item | +| =C-c C-d= | =org-deadline= | Add deadline | +| =C-<return>= | =org-insert-heading-respect-content= | Insert heading while respecting subtree content | + +** Capture Template Keys + +| Key | Template | Target | +|-----+----------+--------| +| =i= | Inbox | Inbox | +| =t= | Task | Tasks | +| =q= | Question | Questions | +| =m= | Meeting | Meetings | +| =r= | Recurring | Recurring | + +** Org Speed Commands + +Speed commands are available at the beginning of a headline when point is in a valid speed-command position. +This configuration uses Org's standard built-in speed commands. + +*** Outline Navigation + +| Key | Command | +|-----+---------| +| =n= | next visible heading | +| =p= | previous visible heading | +| =f= | next heading at same level | +| =b= | previous heading at same level | +| =F= | next block | +| =B= | previous block | +| =u= | up heading | +| =j= | =org-goto= | +| =g= | refile to current location history with prefix behavior | + +*** Outline Visibility + +| Key | Command | +|-----+---------| +| =c= | cycle current subtree | +| =C= | cycle whole buffer | +| =SPC= | display outline path | +| =s= | toggle narrow to subtree | +| =k= | cut subtree | +| === | column view | + +*** Outline Structure Editing + +| Key | Command | +|-----+---------| +| =U= | move subtree up | +| =D= | move subtree down | +| =r= | promote/right shift heading | +| =l= | demote/left shift heading | +| =R= | shift subtree right | +| =L= | shift subtree left | +| =i= | insert heading respecting content | +| =^= | sort subtree | +| =w= | refile | +| =a= | archive subtree with confirmation | +| =@= | mark subtree | +| =#= | toggle comment | + +*** Clock Commands + +| Key | Command | +|-----+---------| +| =I= | clock in | +| =O= | clock out | + +*** Metadata Editing + +| Key | Command | +|-----+---------| +| =t= | change TODO state | +| =,= | set priority | +| =0= | clear priority | +| =1= | set priority A | +| =2= | set priority B | +| =3= | set priority C | +| =:= | set tags | +| =e= | set effort | +| =E= | increase effort | +| =W= | set appointment warning minutes | + +*** Agenda and Search + +| Key | Command | +|-----+---------| +| =v= | open agenda | +| =/= | sparse tree | + +*** Miscellaneous + +| Key | Command | +|-----+---------| +| =o= | open at point | +| =?= | show speed command help | +| =<= | set subtree restriction lock | +| =>= | remove restriction lock | + +* Notes On Behavior + +** Refile + +Use =w= as the stock Org speed command for refile, or =C-c C-w= outside speed-command context. + +** Narrowing + +Use =s= as the stock speed command for toggling subtree narrowing. +This configuration intentionally does not replace it with custom bindings. + +** Archive + +Use =a= as the stock archive speed command with confirmation, or use =C-c $= for the direct archive command. + +** Internal Links + +This setup is intended to work with heading links like: + +#+begin_example +[[*Heading]] +#+end_example + +It does not switch Org into an ID-based linking workflow. |