1 files changed, 145 insertions, 0 deletions
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.