Add Org workflow documentation

1 files changed, 253 insertions, 0 deletions

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.