1 files changed, 213 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ed0aa86
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,213 @@
+# AGENTS.md
+
+## Project scope
+
+This repository is a compact personal Emacs 30 configuration centred on Org mode as the primary work surface.
+
+The live configuration is intentionally small:
+
+- `early-init.el`
+- `init.el`
+
+Treat this as a standalone project. Do not assume hidden modules, generated files, or an older architecture unless the user explicitly adds them.
+
+The immediate focus of the project is the Org core workflow rather than feature expansion. Prioritise the quality of the main operating loop:
+
+- agenda
+- capture
+- refile
+- archive
+- speed commands
+- narrowing and widening
+- predictable window behaviour
+- heading-centric navigation
+
+Use `todo.md` as the working list of intended improvements and constraints when it is present in the repo.
+
+## Role and technical standard
+
+Operate as an Emacs Lisp expert working with Emacs 30.
+
+Changes must be:
+
+- idiomatic Elisp
+- consistent with standard Emacs and Org conventions
+- understandable by a human maintaining a small personal config
+- biased toward built-in behaviour before custom behaviour
+
+Do not treat this as a generic editor customisation exercise. Treat it as careful Elisp work on a deliberately small system.
+
+## Design principles
+
+### 1. Keep the configuration small
+
+Prefer direct configuration over abstraction.
+
+- Use built-in variables, hooks, keybindings, and package options first.
+- Avoid turning a small config into a framework.
+- Do not split code into extra files or modules unless explicitly asked.
+- Do not introduce subsystems because they seem generally useful.
+
+### 2. Prefer stock Emacs and package behaviour
+
+Customise packages within their normal boundaries.
+
+- Prefer supported configuration variables and documented hooks.
+- Avoid wrapping or extending packages with bespoke behaviour unless there is a real gap.
+- Do not build custom behaviour when standard Org functionality already solves the problem well enough.
+
+### 3. Be judicious with helper functions
+
+Minimise helper functions.
+
+- Do not add helpers when a direct configuration form is clear and acceptable.
+- Add a helper only when it materially improves clarity, correctness, reuse, or error handling.
+- When a new helper or constant is justified, namespace it with the `ss-` prefix.
+- Keep helpers small, local in intent, and easy to inspect.
+
+If a change would introduce several helpers or a mini-abstraction layer, that is usually a sign the design should be simplified.
+
+### 4. Optimise for robustness, not cleverness
+
+The configuration should not be brittle.
+
+- Handle missing files gracefully.
+- Handle missing directories gracefully.
+- Handle missing external executables or optional dependencies gracefully.
+- Prefer clear failure modes and useful messages over silent breakage.
+- Avoid partial setup that leaves inconsistent state behind.
+
+Do not assume the user's environment is fully prepared.
+
+### 5. Respect the boundary between config and notes
+
+The user's notes live outside this repository, typically under `~/org`.
+
+The configuration may reference that location, but it does not own the note system.
+
+- Do not silently create a large directory structure.
+- Do not overwrite user files.
+- Do not assume every expected file already exists.
+- Check for existence where appropriate.
+- Fail safely and clearly when required files are absent.
+
+The repo configures behaviour. It should not behave like a provisioning tool unless explicitly asked.
+
+### 6. Preserve portability
+
+The configuration should work across macOS, Linux, and Windows where practical.
+
+- Avoid platform-specific assumptions unless unavoidable.
+- Be careful with path handling.
+- Be careful with executable discovery.
+- Be careful with shell-specific behaviour.
+- Prefer portable Emacs primitives over platform-bound shortcuts.
+
+When platform-specific logic is genuinely needed, keep it explicit and narrow.
+
+## Change bias
+
+When making changes, prefer work that strengthens the current Org operating model instead of adding adjacent capabilities.
+
+Good changes usually improve one of these:
+
+- friction of capture
+- clarity of agenda
+- refile and archive ergonomics
+- navigation speed
+- heading-based work patterns
+- modal and predictable window behaviour
+- resilience when files or tools are missing
+
+Avoid speculative extras unless the user explicitly asks for them.
+
+## Style guidance for code changes
+
+- Prefer clear, flat code over clever abstractions.
+- Prefer explicit names over short opaque ones.
+- Keep comments useful and sparse.
+- Do not add comments that merely restate the code.
+- Use `defconst`, `defvar`, and helper functions only when they add real value.
+- Namespace constants, variables, and helpers with `ss-` when introducing project-owned definitions.
+- Keep custom code small and close to the behaviour it supports.
+- Prefer docstrings on non-trivial functions and user commands.
+- Keep docstrings short, factual, and action-oriented.
+
+## Package and dependency stance
+
+Prefer built-in packages and standard Org features first.
+
+When using third-party packages:
+
+- keep the package set small
+- use them for clear workflow wins
+- configure them conservatively
+- avoid deep custom extensions unless necessary
+
+Do not add a package when built-in Emacs or Org can solve the problem simply enough.
+
+## User experience stance
+
+This project values a calm, dependable workflow over a feature-rich one.
+
+Changes should aim for:
+
+- predictable windows
+- low-friction capture
+- fast movement through headings
+- minimal surprise
+- explicit behaviour
+- simple recovery when something is missing
+
+Avoid adding UI noise, background magic, or hidden automation unless explicitly requested.
+
+## Maintenance rules
+
+### Updating `todo.md`
+
+When `todo.md` is present, treat it as the current backlog for the Org core workflow.
+
+- Align proposed work to that list unless the user explicitly changes direction.
+- Do not rewrite or reorganise `todo.md` without being asked.
+- Mark items complete only when the implementation actually covers them.
+- Do not mark exploratory discussion as completed work.
+- If a change materially affects an item in `todo.md`, mention that connection clearly.
+
+### Preserving intent in `init.el` and `early-init.el`
+
+- Keep `early-init.el` limited to true early startup concerns.
+- Keep operational behaviour in `init.el` unless there is a strong reason otherwise.
+- Avoid scattering related behaviour across distant sections when a local edit is clearer.
+- Do not introduce generated-file workflows unless explicitly requested.
+
+### Editing discipline
+
+- Make the smallest coherent change that solves the problem.
+- Do not refactor unrelated parts of the config while addressing a narrow request.
+- Preserve existing behaviour unless the requested change should alter it.
+- If a simplification removes custom code in favour of stock behaviour, prefer that.
+- Avoid placeholder abstractions for imagined future needs.
+
+## What to avoid
+
+Avoid the following unless the user asks for them:
+
+- large helper layers
+- package-specific mini-frameworks
+- hidden bootstrapping of external note files
+- aggressive auto-creation of directories or content
+- over-designed metadata schemes
+- custom behaviour that fights normal Org conventions
+- platform-specific shortcuts presented as universal solutions
+
+## Output expectations
+
+When proposing or implementing changes:
+
+- keep the solution scoped to the user's request
+- preserve the small-project character of the repo
+- explain trade-offs plainly when they matter
+- prefer the simplest correct implementation
+- do not broaden scope without a strong reason
+
+If a design can be solved either with stock configuration or custom machinery, choose stock configuration unless there is a clear downside.