path: root/README.md

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

Journal capture uses a Year -> Day outline in `journal.org` with explicit
`Tasks`, `Notes`, and `Meetings` headings beneath each day entry.

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

## Keybindings

The main bindings are:

- `C-c a` for the agenda
- `C-c c` for capture
- `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 MOC
- `C-c n d` to open `~/org/journal.org`
- `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.