From d371b31193db10934a8815a7e6dbc4193ee1eb60 Mon Sep 17 00:00:00 2001
From: Ayo <ayo@ayco.io>
Date: Fri, 3 Jul 2026 10:24:55 +0200
Subject: [PATCH] chore: initial AGENTS instructions

---
 AGENTS.md | 29 +++++++++++++++++++++++++++++
 CLAUDE.md |  5 +++++
 2 files changed, 34 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..399d6e5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,29 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository.
+
+## What this is
+
+Ayo's personal dotfiles — configuration for vim/neovim, tmux, mutt (email), and various desktop tools. There is no build or test step; the "product" is the config files themselves, which are deployed to the home directory via symlinks.
+
+## Deploying changes
+
+`install.sh` symlinks the tracked dotfiles into `~` (and shares `.vimrc` with neovim via `~/.config/nvim/init.vim`). Symlinks are relative (`ln -rsf`), so editing a file in this repo immediately affects the live config — no re-run needed after the initial link. Re-run `install.sh` only when adding a *new* file that needs linking.
+
+```bash
+sh install.sh
+```
+
+Node/pnpm are present only for husky git hooks (`pnpm install` runs `husky` via the `prepare` script). There is no application code and `pnpm test` is a stub that always fails.
+
+## Layout notes
+
+- **`.vimrc`** — shared verbatim by both vim and neovim. Plugins are managed by **Vundle** (`:PluginInstall` after editing the plugin list). Uses ALE for linting/fixing with `fix_on_save` on (JS: eslint + prettier; all files: trim whitespace). NERDTree opens on startup; leader-style window nav is remapped to `g h/j/k/l`; `jj`-style escapes and `J`/`K` = 5-line jumps are the core custom motions.
+- **`vscode-settings.json`** — mirrors the same vim motions (`jj` to escape, `J`/`K` jumps, `gj`/`gk`) via the VSCode vim extension, kept intentionally consistent with `.vimrc`. It is *not* symlinked by `install.sh`; copy it into VSCode's settings manually.
+- **`.tmux.conf`** — plugins via **tpm** (`<prefix> I` to install). Split binds are `\` and `-`; pane nav is `Ctrl-h/j/k/l`; theme is tmux-nova. Requires Nerd Fonts and, for the git segment, the `gitmux` binary (see README).
+- **`.muttrc`** — depends on files NOT in this repo: `~/.mutt/secrets.rc` (smtp/imap creds), `~/.mutt/gpg.rc`, and `~/.mutt/aliases`. HTML mail is rendered through `.mailcap` (links2). Signs mail with PGP. Folder shortcuts are `g<letter>` (gh inbox, ga archive, etc.).
+
+## Conventions
+
+- Vim-style motion remaps (`jj` escape, `J`/`K` = 5 lines, `gj`/`gk` visual line movement) are duplicated across `.vimrc` and `vscode-settings.json` — keep them in sync when changing one.
+- Themes are toggled by commenting/uncommenting blocks rather than deleting (see the tmux theme section and the vim `colorscheme` lines); preserve that pattern.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..debc328
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+See [AGENTS.md](AGENTS.md) for all repository guidance.