#+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

** Required Files

The main work note is =~/org/optus.org=.
The people CRM is =~/org/crm.org=.

Startup validates =~/org=, =~/org/optus.org=, and =~/org/crm.org=.
If any of them are missing, Emacs still starts, but the workflow warns clearly so the missing file can be fixed deliberately.

* 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

All capture templates target headings in =~/org/optus.org=.

* CRM Workflow

The CRM is a single Org file at =~/org/crm.org=.
Each person is stored as a level-1 heading with this property model:

#+begin_src org
:PROPERTIES:
:ABBREV:
:ALIASES:
:ROLE:
:TEAM:
:MANAGER:
:RELATIONSHIP:
:ENGAGEMENT:
:SUPPLIER:
:LOCATION:
:CURRENT_FOCUS:
:END:
#+end_src

The configured relationship completions are:

- =Peer=
- =Direct Report=
- =Internal Stakeholder=
- =External Stakeholder=
- =Vendor=

Role, team, relationship, engagement, supplier, and location prompts offer known values with completion.
Relationship also allows new freeform values when needed.
Manager completion is restricted to existing CRM names.

** CRM Commands

- =C-c p o= opens =~/org/crm.org= in overview mode
- =C-c p f= finds a person and narrows to that card
- =C-c p a= adds a new CRM card
- =C-c p i= inserts a canonical person name
- =C-c p s= inserts a compact person summary

Reports are available through these commands:

- =M-x ss-crm-report-by-role=
- =M-x ss-crm-report-by-team=
- =M-x ss-crm-report-by-manager=
- =M-x ss-crm-report-by-relationship=
- =M-x ss-crm-report-by-engagement=
- =M-x ss-crm-report-by-supplier=
- =M-x ss-crm-report-by-location=

** CRM Completion

CRM completion works in text and Org writing buffers through both abbrevs and completion-at-point.
Vertico remains the minibuffer completion UI, while Corfu provides the in-buffer popup for completion at point.

- CAPF inserts canonical names
- aliases help find the right person
- Corfu shows the completion popup for CRM CAPF in Org and text buffers
- Marginalia annotations show compact CRM summaries in minibuffer selection
- CRM abbrevs are rebuilt from the current CRM data, and stale CRM abbrevs are cleared before reinstalling them

* 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 p o= | =ss-crm-open= | Open CRM in overview mode |
| =C-c p f= | =ss-crm-find= | Find and focus a CRM card |
| =C-c p a= | =ss-crm-add= | Add a CRM card |
| =C-c p i= | =ss-crm-insert-name= | Insert a canonical CRM name |
| =C-c p s= | =ss-crm-insert-summary= | Insert a compact CRM summary |
| =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.