From 4ba2472236717de99f38a699171a98532a968056 Mon Sep 17 00:00:00 2001
From: Jens Luedicke <jens@luedicke.me>
Date: Wed, 10 Sep 2025 07:40:57 +0200
Subject: [PATCH] Add CLAUDE.md for Claude Code guidance
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added comprehensive documentation for Claude Code instances working with this
Emacs configuration, including:
- Core commands for configuration management and emergency fixes
- High-level architecture overview and module organization
- Key operational notes about CUA mode, completion system, and keybindings

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5aada7f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a modular Emacs configuration with 33+ configuration modules in the `lisp/` directory. The configuration is designed for software development with support for multiple languages, LSP, version control, and various productivity tools.
+
+## Core Commands
+
+### Configuration Management
+```elisp
+M-x reload-emacs-config        ; Reload entire configuration
+M-x byte-compile-config        ; Byte-compile all config files for faster loading
+M-x clean-byte-compiled-files  ; Remove all .elc files
+M-x byte-compile-init-files    ; Compile only lisp/ directory files
+```
+
+### Emergency Fixes
+```elisp
+M-x fix-editing-now            ; Emergency restore editing capability
+M-x diagnose-editing-issue     ; Diagnose why editing is disabled
+M-x diagnose-cua-selection     ; Debug CUA mode and selection issues
+M-x diagnose-key-conflicts     ; Debug keybinding conflicts
+C-c C-!                        ; Quick emergency fix keybinding
+C-c C-?                        ; Quick diagnosis keybinding
+```
+
+### Package Management
+```elisp
+M-x package-refresh-without-proxy  ; Refresh packages bypassing proxy
+M-x package-install-without-proxy  ; Install package bypassing proxy
+M-x install-dev-packages           ; Install common development packages
+M-x toggle-proxy                   ; Toggle proxy settings on/off
+```
+
+### Development Modes
+```elisp
+M-x enable-dev-mode-modern    ; Enable Eglot-based development mode
+M-x enable-dev-mode           ; Enable LSP-mode based development (legacy)
+M-x disable-eslint-in-buffer  ; Disable ESLint in current buffer
+```
+
+## Architecture
+
+### Module Loading Order (init.el)
+1. **Emergency fixes** (`init-emergency-fix`) - Loaded first to ensure editing works
+2. **Core modules** - Package management, completion, UI, editor settings
+3. **Development tools** - Project management, VCS, LSP, treesitter
+4. **Optional configs** - Loaded conditionally if files exist
+
+### Key Configuration Modules
+
+**Core System:**
+- `init-core.el` - Package management with use-package
+- `init-completion.el` - Company mode for auto-completion (replaced Corfu)
+- `init-ui.el` - CUA mode configuration, themes, display settings
+- `init-editor.el` - Selection keybindings, shift-selection fixes
+
+**Development:**
+- `init-eglot.el` - Built-in LSP client configuration
+- `init-treesitter.el` - Tree-sitter support for Emacs 29+
+- `emacs-dev-config-modern.el` - Modern development setup with Eglot
+- `emacs-dev-config.el` - Legacy LSP-mode configuration
+
+**Fix Modules:**
+- `init-emergency-fix.el` - Emergency editing restoration
+- `init-eslint-fix.el` - ESLint configuration handling
+- `init-seq-fix.el` - Seq library compatibility fixes
+
+**Applications:**
+- `elfeed-config.el` - RSS reader with CUA mode fixes
+- `portfolio-tracker-v2.el` - Investment portfolio tracking
+- `mu4e-config.el` - Email client configuration
+
+### CUA Mode and Keybinding Architecture
+
+The configuration uses CUA mode for standard copy/paste (C-c, C-v, C-x) but disables it in special modes where single-key commands are needed:
+- Elfeed buffers
+- Magit
+- Dired
+- Portfolio tracker
+
+C-Shift-Arrow word selection is specially configured to work with CUA mode through custom functions in `init-editor.el`.
+
+### Completion System
+
+Uses Company mode with:
+- Auto-completion after 2 characters
+- 0.2 second delay
+- Tab/Shift-Tab navigation
+- Multiple backends configured
+
+### Custom Keybindings
+- `C-c C-r` - Reload configuration
+- `C-c C-d c` - Diagnose CUA/selection
+- `C-c C-d k` - Diagnose key conflicts
+- `C-x w` - Open Elfeed RSS reader
+- `C-c $` - Open portfolio tracker
+
+## Important Notes
+
+- The configuration automatically disables CUA mode in special modes to preserve single-key commands
+- ESLint is automatically disabled if no configuration file is found in the project
+- Proxy settings can be toggled for package installation (default: eudewerepo001:3128)
+- Byte-compilation is recommended for faster startup (`M-x byte-compile-config`)
+- Emergency fix functions are available if editing becomes disabled
\ No newline at end of file