1 files changed, 58 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b2718a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+# emacs_setup
+
+Git-tracked Emacs configuration. `emacs.el` is the source of truth;
+`~/.emacs` is a symlink to it, so the live config is always the latest
+version in this repo.
+
+## Layout
+
+| File         | Purpose                                          |
+|--------------|--------------------------------------------------|
+| `emacs.el`   | The init file itself (what `~/.emacs` points to) |
+| `check.sh`   | Validate the config loads cleanly                |
+| `install.sh` | Back up old config, symlink `~/.emacs` → `emacs.el` |
+| `backups/`   | Pre-install backups (gitignored)                 |
+
+## Usage
+
+```sh
+./install.sh     # one-time: symlink ~/.emacs -> emacs.el (backs up the old file)
+./check.sh       # or: make check -- run before committing
+make status      # see uncommitted drift
+```
+
+### Workflow after installing
+
+- Edit the config either in Emacs (`C-x C-f ~/.emacs`) or here — same file.
+- Changes made by `M-x customize` (custom-set-variables) land directly
+  in this working tree; review with `git diff`, commit when happy.
+- To try a change: save, `./check.sh`, then restart Emacs.
+- To roll back: `git checkout <commit> -- emacs.el` — the symlink picks
+  it up immediately, no reinstall.
+- To restore the pre-repo config entirely: copy the newest file from
+  `backups/` back to `~/.emacs` (replacing the symlink).
+
+## Findings from the initial check (2026-09-10)
+
+Fixed in a follow-up commit:
+
+1. **Missing `lexical-binding` cookie** — startup warning on every launch. Added
+   `-*- lexical-binding: t; -*-` to line 1 (verified the file loads cleanly
+   under lexical binding).
+2. **Unguarded Verilog LSP client** — the config registers `verible-verilog-ls`
+   and hooks `lsp` into `verilog-mode`, but the binary is not installed, so
+   opening Verilog files errored. Now registered only when the binary exists
+   (`executable-find`). Install `verible` to re-enable.
+
+Known quirks left as-is (deliberate-looking choices — revisit if annoying):
+
+- **`lsp-mode` and `eglot` are both active**: lsp-mode owns C/C++/Verilog/VHDL/
+  LaTeX, eglot owns Java/Scala/Python/Clojure. The C/C++ overlap is noted in
+  the config itself. Works, but pick one eventually.
+- **`jdtls` is not installed**, so Java files will fail to start eglot.
+  Install `jdtls` (or drop java-mode from the eglot hook).
+- **`flycheck-c/c++-gcc-executable` is set to `/usr/bin/avr-gcc`** in
+  `custom-set-variables` — flycheck uses avr-gcc for *all* C files, not just
+  AVR projects. Consider moving it to per-project `.dir-locals.el`.
+- helm and vertico/consult are both configured (two completion stacks);
+  helm is only used for gtags navigation.