# 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 configuration source is `config.org`; `init.el` and `early-init.el` are generated from it.

## System Model

This repository configures Emacs. It does not define, create, or validate the `~/org` note system.

- `config.org` is the source of truth for Emacs configuration only.
- `~/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/moc.org` is a normal note. The configuration may open it, but it must not create or manage it.
- PARA is the organising model for durable notes. Folder placement carries meaning, and workflows must respect that placement.
- The system optimises for speed of capture and minimal friction.
- The system must prefer explicit rules over implicit behaviour and must avoid over-structuring, manual overhead, and inconsistency.

## External Invariants

These are external note-system invariants. The configuration assumes them, but it does not manage them.

- `~/org` must exist.
- `~/org/moc.org` must exist.
- `~/org/areas/people/people.org` must exist.

## Emacs Setup

### Source of truth and generated files

`config.org` is the only file intended for manual Emacs 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.
- `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.
- `gptel` with the GitHub Copilot backend, currently being trialled as an experimental tool rather than a defined workflow.
- `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 organised like this:

- `daily/` for plain daily Org files.
- `projects/` for project notes.
- `areas/` for area notes.
- `areas/people/people.org` for the structured people system.
- `resources/` for reference material.
- `archives/` for archived notes.

This is a PARA-style layout. Folder placement carries meaning. Denote keywords are used sparingly, with `project` kept as the only built-in structural keyword because project titles are often ambiguous outside their folder.

### Agenda Rules

The agenda is rule-based.

- The agenda must include recursive scans of `.org` files under `~/org/projects/`, `~/org/areas/`, and `~/org/resources/`.
- The agenda must exclude `~/org/daily/` and `~/org/archives/`.
- The agenda must use recursive discovery and explicit include and exclude rules rather than heuristic selection.

### Completion setup

The minibuffer stack is intentionally small:

- `vertico` provides the completion UI.
- `orderless` handles matching.
- `marginalia` adds annotations.
- `corfu` handles in-buffer completion popups for text and Org buffers.

## People System

The people system is a structured people system (lightweight CRM) rooted at `~/org/areas/people/people.org`.

- Each top-level heading represents one person.
- Entries are strictly structured around heading text and properties.
- The system generates abbrevs from the people file.
- The system provides canonical-name completion through a CAPF.
- The system provides reporting views grouped by person properties.
- The system rebuilds on any people-file change, whether the change comes from manual editing or from a command.
- The system must remain up to date after changes.
- Failures must surface visibly. The system must not silently fall back to stale state.
- `CURRENT_FOCUS` must stay short and phrase-like so summaries and completion annotations remain readable.

Name entry uses fixed abbrevs plus the structured people system:

- `abbrev` provides deterministic one-shot shortcuts for fixed name expansions.
- people-specific abbrevs are generated from top-level cards in `~/org/areas/people/people.org`.
- a CAPF feeds Corfu canonical names from `~/org/areas/people/people.org`, while alias matching stays available for lookup and completion.
- Marginalia annotates person candidates with `role | location | engagement | current focus`.
- `M-x ss/people-open` opens `~/org/areas/people/people.org` in overview mode through `ss/people-overview`.
- `M-x ss/people-find` opens a person card narrowed to that subtree.
- `M-x ss/people-overview` opens the people file in overview mode, resetting the file by widening and restoring the overview when leaving card view.
- `M-x ss/people-insert-name` inserts the canonical name at point.
- `M-x ss/people-insert-summary` inserts a compact single-line summary at point.
- `M-x ss/people-add` adds a new person card directly to `~/org/areas/people/people.org`.
- `M-x ss/people-report-by-relationship`, `M-x ss/people-report-by-engagement`, `M-x ss/people-report-by-role`, and `M-x ss/people-report-by-location` render grouped Org reports in a read-only buffer.

### Persistent abbrevs

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 not stored in a separate file. They are rebuilt from `~/org/areas/people/people.org` whenever the people file changes, and missing `ABBREV` properties fall back to a generated default trigger.

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

### MOC

`~/org/moc.org` is a normal note. It serves as a small curated navigation surface rather than an exhaustive index or system of record, and the configuration assumes the file already exists.

The configuration may open the MOC automatically on startup, and `C-c n M` opens it manually. The configuration must not create or manage the file.

Its Quick Access section provides actionable links for opening the agenda, today's note, capture, and a new note, while the rest of the file stays lightweight and curated around active projects, areas, and a few high-leverage resources.

### Capture Model

The capture model has two distinct modes.

### Daily notes

Daily notes are plain Org files in `~/org/daily/`, named by date. The workflow expects these headings:

- `Tasks`
- `Notes`
- `Open Loops`

Daily notes are a work journal. They use light structure and are optimised for speed.

### Durable notes

Durable notes use Denote and live in the PARA directories under `~/org/`.

- Durable notes are created through capture plus Denote.
- Durable notes are structured at creation time.
- Folder placement carries meaning.
- The workflow must respect PARA placement rather than relying on later manual cleanup.

### Agenda usage

The agenda is opened through `ss/open-agenda`, bound to `C-c a`. That command explicitly loads `org-agenda`, and the config refreshes `org-agenda-files` immediately before each `org-agenda` invocation.
Agenda file selection follows the canonical rules in the `Agenda Rules` section above.

### 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, and resources

Daily task capture writes under `Tasks`. Daily note capture and daily meeting capture both write under `Notes`, and the meeting template prefixes the heading with a timestamp and the word `meeting`.

Denote captures still prompt for title, keywords, and subdirectory placement where appropriate, but folder placement does most of the classification work. The project capture template prepopulates the `project` keyword. Area and resource captures do not inject structural keywords automatically, and there is no Denote-backed meeting capture template.

The structured people system is intentionally outside `org-capture`: `M-x ss/people-add` writes a compact card directly into `~/org/areas/people/people.org`, keeping the people file as a fast reference file instead of another capture sink.

### 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 open the central MOC note.
- `C-c n E` to show people grouped by engagement.
- `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 L` to show people grouped by location.
- `C-c n d` to open today's daily note.
- `C-c n o` to restore the people overview.
- `C-c n O` to show people grouped by role.
- `C-c n p` to open `~/org/areas/people/people.org`.
- `C-c n P` to add a new person card.
- `C-c n R` to show people grouped by relationship.

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, with folder placement carrying most of the durable type information.

### 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 configuration must not enforce policy for add, push, debounce, or commit-message behaviour.

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))))))
```

That applies to buffers visiting files under `~/org/` and its subdirectories. The repository-local settings control whether new files are added, whether pushes occur, how long commits are debounced, and what commit message is used, while the Emacs config supplies the package itself and picks the correct shell command separator for the active shell.

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