# AGENTS.md

## Project Purpose

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

## Repository Layout

- `config.org` is the single hand-edited source of truth for the configuration.
- `init.el` and `early-init.el` are generated from `config.org` and should not be edited directly.
- Structure the literate config by startup responsibility first, then by workflow domain.
- The current Org workflow lives under `~/org/` with `daily/`, `projects/`, `areas/`, `areas/people/`, `resources/`, and `archives/`.
- Daily notes stay as plain Org files under `~/org/daily/`; longer-lived notes are handled through Denote in the same root.
- Agenda files are discovered dynamically from the project, area, and resource directories rather than from a fixed file list.
- The config also includes a small gptel workflow 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 `config.org` first, then regenerate the derived files instead of patching generated output by hand.
- Preserve existing Emacs Lisp style and naming where patterns already exist.
- Avoid unrelated refactors while working on a specific configuration task.
- Keep narrative prose close to the configuration it explains, especially around the note-taking workflow and startup behavior.
- 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.
- If the literate file starts to lose coherence, improve its sectioning and prose before introducing new generated helper files.

## Validation Expectations

- For Emacs Lisp changes, tangle `config.org` and verify the generated configuration loads cleanly before claiming completion.
- 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 generated startup path rather than any retired hand-maintained module layout.
- 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 configuration in `config.org`.
- 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.
- 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.
- Update AGENTS.md when the repo workflow, Org layout, or verification expectations materially change.
- Keep AGENTS.md concise and update it only when the repository structure or working rules actually change.