# AGENTS.md

## Project Purpose

This repository is for the creation and maintenance of Emacs 30 configuration
files.

## Repository Layout

- `init.el` is the hand-edited runtime entry point.
- `early-init.el` is the hand-edited early startup file.
- Runtime implementation lives in domain modules under `lisp/`.
- Keep the module set reasonably chunky and domain-based:
  `ss-core.el`, `ss-ui.el`, `ss-org.el`, `ss-agenda.el`, `ss-capture.el`,
  `ss-denote.el`, `ss-crm.el`, `ss-gptel.el`, and `ss-keys.el`.
- The current Org workflow lives under `~/org/` with `journal.org`, `daily/`,
  `projects/`, `areas/`, `areas/people/people.org`, `resources/`, and
  `archives/`.
- `~/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. The
  configuration may open it, but it must not create or manage it.
- `~/org/moc.org` is a normal note. It must already exist. The configuration
  may open it, but it must not create or manage it.
- `~/org/areas/people/people.org` is the people CRM file. It must already
  exist. The configuration may open it, but it must not create or manage it.
- Agenda files are discovered by explicitly including `~/org/journal.org` and
  recursively scanning `.org` files under `~/org/projects/`, `~/org/areas/`,
  and `~/org/resources/`.
- Agenda discovery must exclude `~/org/archives/`.
- PARA is the organising model for durable notes, and folder placement carries
  meaning.
- The config includes an experimental `gptel` setup that uses GitHub Copilot
  as the backend.
- Do not treat `auto-save-list/` as source content.

## Editing Expectations

- Prefer small, focused changes over broad rewrites.
- Edit `init.el`, `early-init.el`, and the relevant `lisp/` modules directly.
- Keep `init.el` as the central composition layer with explicit feature
  inclusion.
- Keep side effects out of require time where practical; modules should expose
  setup functions.
- Preserve existing Emacs Lisp style and naming where patterns already exist.
- Avoid unrelated refactors while working on a specific configuration task.
- Be explicit about GUI-versus-terminal behavior. If a change affects
  `emacs -nw`, avoid moving terminal UI changes earlier in startup unless that
  timing is intentional.

## Validation Expectations

- For Emacs Lisp changes, verify the hand-edited startup path directly.
- When Emacs is available, prefer a batch check such as
  `emacs --batch -Q --load ./init.el` from the repository root.
- Keep regression checks aligned with the modular startup path documented in
  `README.md`.
- For changes that affect terminal Emacs behavior, verify in an actual
  `emacs -nw` session as well as batch mode; batch load alone will not catch
  interactive tty regressions.

## Git Workflow Expectations

- Use a git-based workflow for repository changes.
- Assume changes will be committed incrementally as the work progresses.
- Keep changes small and focused so they can be reviewed and committed
  independently.
- Treat verification as the gate for each commit-sized unit of work.
- After verification passes for a unit of work, summarize the result and prompt
  the user before creating the commit.
- Keep commit messages concise and specific to the verified change.
- Do not bundle unrelated changes into the same commit.

## Documentation Expectations

- Document non-obvious conventions close to the relevant Lisp module.
- Update `README.md` whenever configuration or workflow changes alter package
  usage, startup behavior, keybindings, directory layout, capture flow, or
  other documented behavior.
- `README.md` must describe the current configuration truthfully. Do not leave
  stale documentation behind and do not document planned behavior as current
  behavior.
- Keep `README.md` and `AGENTS.md` in sync with the modular architecture.
- Use `~/org` consistently when describing the external notes directory.
- Before claiming a change is complete or asking to commit it, review whether
  `README.md` needs an update; if it does not, say so explicitly in the
  summary.
- Keep `AGENTS.md` concise and update it only when the repository structure or
  working rules actually change.