diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 284 |
1 files changed, 0 insertions, 284 deletions
diff --git a/README.md b/README.md deleted file mode 100644 index da53922..0000000 --- a/README.md +++ /dev/null @@ -1,284 +0,0 @@ -# Emacs Configuration - -This repository contains a modular Emacs configuration built around Org mode, -Denote, a PARA-style note layout, a people CRM, and a small completion stack. -`init.el` is the hand-edited entry point, `early-init.el` handles true early -startup concerns, and the runtime implementation is hand-edited across the -domain modules under `lisp/`. - -## System Model - -This repository configures Emacs. It does not define, create, or validate the -`~/org` note system. - -- `init.el` is the source of truth for runtime composition and feature - selection. -- `early-init.el` is the source of truth for true early startup settings. -- `lisp/ss-*.el` is the source of truth for the runtime implementation by - domain. -- `~/org` is external to this repository and must already exist. -- The configuration may open files in `~/org`, but it must not create - directories, create files, or validate note structure. -- `~/org/journal.org` is the operational journal. It must already exist, and - the configuration may open it but must not create or manage it. -- `~/org/moc.org` is a normal note. It must already exist, and the - configuration may open it but must not create or manage it. -- `~/org/areas/people/people.org` is the people CRM file. It must already - exist, and the configuration may open it but must not create or manage it. -- PARA is the organising model for durable notes. Folder placement carries - meaning, and workflows must respect that placement. - -## Repository Layout - -The runtime architecture is: - -```text -early-init.el -init.el -lisp/ - ss-core.el - ss-ui.el - ss-org.el - ss-agenda.el - ss-capture.el - ss-denote.el - ss-crm.el - ss-gptel.el - ss-keys.el -``` - -The module responsibilities are: - -- `ss-core.el` bootstraps packages, defines shared paths and helpers, and - applies shared editor defaults. -- `ss-ui.el` owns theme, fonts, frame behavior, modeline, and completion UI. -- `ss-org.el` owns base Org setup, startup MOC behavior, and shared note - helpers. -- `ss-agenda.el` owns agenda discovery and agenda commands. -- `ss-capture.el` owns journal capture structure and capture templates. -- `ss-denote.el` owns Denote setup and durable-note capture helpers. -- `ss-crm.el` owns all people CRM behavior. -- `ss-gptel.el` owns the experimental GitHub Copilot-backed `gptel` setup. -- `ss-keys.el` owns global keybindings only. - -`init.el` enables high-level features centrally through `ss-enabled-features`. -Feature toggling works by including or excluding a module there. - -## Package Model - -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. - -The current setup uses: - -- `org` and `org-capture` for agenda and journal capture -- `denote` for durable notes, naming, keywords, and linking -- `git-auto-commit-mode` for optional automatic commits inside `~/org` when - enabled by directory-local settings -- `vertico` for minibuffer completion UI -- `orderless` for flexible completion matching -- `marginalia` for minibuffer annotations -- `corfu` for in-buffer completion popups in text and Org buffers -- `olivetti` for centered writing layout in Org buffers -- `gptel` with the GitHub Copilot backend as an experimental tool -- `dired` with a macOS-safe `ls` configuration -- `time` for the modeline clock -- `modus-themes`, using `modus-vivendi` - -## Org Layout - -The note system lives under `~/org/` and is organised like this: - -- `journal.org` for the operational journal -- `daily/` for older daily Org files that may still exist -- `projects/` for project notes -- `areas/` for area notes -- `areas/people/people.org` for the people CRM -- `resources/` for reference material -- `archives/` for archived notes - -Agenda discovery is rule-based: - -- include `~/org/journal.org` -- recursively scan `.org` files under `~/org/projects/`, `~/org/areas/`, and - `~/org/resources/` -- exclude `~/org/archives/` - -## People CRM - -The people workflow is a CRM rooted at `~/org/areas/people/people.org`. - -- each top-level heading represents one person -- entries are structured around heading text and flat properties -- the system rebuilds people abbrevs from the CRM file -- a CAPF provides canonical-name completion while alias matching remains - available for lookup -- Marginalia annotates people with `role | team | engagement | current focus` -- reports are available by role, team, manager, engagement, supplier, and - location -- `TEAM` captures the current working team and `MANAGER` captures the formal - organisational manager -- person cards use `ROLE`, `TEAM`, `MANAGER`, `ENGAGEMENT`, `SUPPLIER`, - `LOCATION`, and `CURRENT_FOCUS` in that order - -The CRM commands are: - -- `M-x ss-crm-open` -- `M-x ss-crm-overview` -- `M-x ss-crm-find` -- `M-x ss-crm-insert-name` -- `M-x ss-crm-insert-summary` -- `M-x ss-crm-add` -- `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-engagement` -- `M-x ss-crm-report-by-supplier` -- `M-x ss-crm-report-by-location` - -Persistent abbrevs live in `abbrev_defs` at the repository root. The config -loads that file on startup, enables abbrev mode only in text-like buffers, and -saves learned abbrevs back to the same file silently when buffers are saved. -People-specific abbrevs are rebuilt from `~/org/areas/people/people.org` -whenever that file changes. - -## Workflow - -`~/org/moc.org` is a normal note. It is treated as a curated navigation note, -not a generated system file. The config may open it on startup, and `C-c n M` -opens it manually. - -The capture model has two distinct paths: - -- fast operational capture goes to `~/org/journal.org` -- durable notes use Denote in the PARA directories under `~/org/` - -`~/org/journal.org` remains the operational capture surface. Journal capture -uses a Year -> Day outline in `journal.org` with explicit `Tasks`, `Notes`, -and `Meetings` headings beneath each day entry. - -Org buffers enable `olivetti-mode` automatically for a centered writing layout -in both GUI and terminal Emacs sessions. - -Invisible edits in Org are blocked with an error rather than silently changing -hidden content. - -Questions that come up during the day can be tracked as Org tasks under the -day's `Tasks` heading. The intended task workflow is `TODO`, `CLARIFY`, -`WAIT`, `DONE`, and `CANCELLED`: use `CLARIFY` for open questions or ambiguity, -and `WAIT` once the question has been asked and the answer is pending. -Completing an item prompts for a note so the answer can be recorded in the -task log, and those state logs are stored in a `LOGBOOK` drawer. - -Org refile uses the current `org-agenda-files` set as its target space and can -move entries to any heading within those files. Refile selection uses full -outline paths, including the file name, so the existing Vertico, Orderless, and -Marginalia stack can present a clearer path-based destination prompt. - -The configured capture templates cover: - -- journal tasks -- journal notes -- journal meetings -- Denote-backed captures for generic notes, projects, areas, and resources - -The people CRM remains outside `org-capture`: `M-x ss-crm-add` writes directly -to `~/org/areas/people/people.org`. - -Navigation history adds a small browser-style back and forward layer on top of -mark-based movement. It records significant note jumps from the custom journal -and MOC commands, CRM find/open commands, `org-open-at-point`, common agenda -jumps, and `denote-open-or-create`, while ignoring ordinary cursor motion and -same-location no-ops. - -## Keybindings - -The main bindings are: - -- `C-c a` for the agenda -- `C-c b` to move back through recorded note and mark navigation history -- `c` inside the agenda dispatcher to show the custom `Clarify items` view for - `CLARIFY` tasks -- `C-c c` for capture -- `C-c f` to move forward again after using navigation back -- `C-c n n` to open or create a Denote note -- `C-c n l` to insert a Denote link -- `C-c n j` to open the full `~/org/journal.org` buffer -- `C-c n M` to open the MOC -- `C-c n d` to open today's journal entry in a focused session; when today's - entry does not yet exist, the command creates it using the normal journal - datetree structure, then narrows to that entry; inside the session, - `C-c C-c` saves and dismisses, and `C-c C-k` dismisses without auto-saving -- `C-c n p` to open the people CRM -- `C-c n P` to add a new person card -- `C-c n f` to find a person card -- `C-c n i` to insert a canonical person name -- `C-c n I` to insert a compact person summary -- `C-c n o` to restore the people overview -- `C-c n O` to show people grouped by role -- `C-c n T` to show people grouped by team -- `C-c n R` to show people grouped by manager -- `C-c n E` to show people grouped by engagement -- `C-c n S` to show people grouped by supplier -- `C-c n L` to show people grouped by location -- `C-c n g` to start `gptel` -- `C-c n s` to send in `gptel` -- `C-c n r` to rewrite with `gptel` -- `C-c n a` to add context in `gptel` - -## Automatic Note Commits - -The configuration provides `git-auto-commit-mode` capability. Behaviour is -defined in `~/org/.dir-locals.el`. - -When enabled in `~/org/.dir-locals.el`, saving a file in `~/org/` makes Emacs -try to commit that change. The Emacs config supplies the package and selects -the shell command separator based on the active shell, while the note tree -defines add, push, debounce, and commit-message behavior. - -Place this file at `~/org/.dir-locals.el`: - -```emacs-lisp -((nil . - ((eval . - (progn - (setq-local gac-automatically-add-new-files-p t - gac-automatically-push-p t - gac-debounce-interval 60 - gac-default-message - (lambda (_filename) - (format-time-string "Auto-commit: %Y-%m-%d %H:%M:%S"))) - (git-auto-commit-mode 1)))))) -``` - -## Validation - -The primary verification command for the runtime path is: - -```sh -emacs --batch -Q --load ./init.el -``` - -`early-init.el` and `init.el` are hand-edited source files, not generated -artifacts. - -## 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 - -- Edit `init.el`, `early-init.el`, and `lisp/ss-*.el` directly. -- Keep this README aligned with the current configuration. -- Keep `README.md` and `AGENTS.md` in sync. -- Do not document planned behavior as if it already exists. |