1 files changed, 125 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..66c87e4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,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`. Before running `org-agenda`, the config refreshes `org-agenda-files` from the PARA directories and explicitly loads `org-agenda` so agenda-specific variables are available.
+
+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.
+\ No newline at end of file