|
1 | 1 | # Dotfiles Repository - Agent Guide |
2 | 2 |
|
3 | | -## ⚠️ DO NOT EDIT - Auto-Generated Files |
4 | | - |
5 | | -- `lazy-lock.json` - Neovim plugin lockfile (managed by Lazy.nvim) |
6 | | -- `Brewfile.lock.json` - Homebrew bundle lockfile |
7 | | -- `.config/nvim/.sessions/`, `.config/nvim/.undo/`, `.config/nvim/.backup/` - Neovim state |
8 | | -- `.config/fish/{fish_variables,completions,conf.d,functions}/` - Fish shell state (managed by fisher) |
9 | | -- `.config/lazygit/state.yml` - Lazygit state |
10 | | -- `.config/ags/@girs/` - AGS TypeScript type definitions (regenerate with `ags types`) |
11 | | -- **Focus on source configs only!** |
12 | | - |
13 | | -## 📦 Repository Overview |
14 | | - |
15 | | -Personal dotfiles managed with GNU Stow for symlink management. Primary configs: |
16 | | - |
17 | | -- **Neovim:** 128+ Lua files, Lazy.nvim plugin manager, LSP, Treesitter, custom utils |
18 | | -- **Shell:** Fish (primary), dash (Cursor/VSCode fallback) |
19 | | -- **Terminal:** WezTerm |
20 | | -- **Display:** Hyprland (Linux) |
21 | | -- **Theme:** Zenwritten Dark (consistent across nvim, wezterm, bat, opencode, etc.) |
22 | | - |
23 | | -## 🔧 Common Operations |
24 | | - |
25 | | -### Setup & Installation |
26 | | - |
27 | | -```bash |
28 | | -brew bundle install # Install/update all dependencies |
29 | | -stow . # Apply dotfiles (creates symlinks from ~/) |
30 | | -stow -n . # Dry-run to preview changes |
31 | | -bash ./scripts/install.sh # Fresh system setup (installs everything) |
32 | | -``` |
33 | | - |
34 | | -### Neovim |
35 | | - |
36 | | -```bash |
37 | | -nvim --headless +"Lazy! sync" +qa # Update plugins |
38 | | -nvim --headless +checkhealth +qa # Validate setup |
39 | | -``` |
40 | | - |
41 | | -### Vicinae Extensions |
42 | | - |
43 | | -```bash |
44 | | -./scripts/vicinae-build-extensions.sh # Build all extensions |
45 | | -# See .config/vicinae/extensions/AGENTS.md for extension development guide |
46 | | -``` |
47 | | - |
48 | | -### Testing Changes |
49 | | - |
50 | | -```bash |
51 | | -fish -c "source ~/.config/fish/config.fish" # Test fish config |
52 | | -bat cache --build # Rebuild bat cache after theme changes |
53 | | -stow -n . # Preview stow changes before applying |
54 | | -``` |
55 | | - |
56 | | -## 📝 Lua Style (Neovim Configs) |
57 | | - |
58 | | -### Module Pattern |
59 | | - |
60 | | -```lua |
61 | | -local M = {} |
62 | | - |
63 | | --- Private function (local) |
64 | | -local function helper_function() |
65 | | - -- implementation |
66 | | -end |
67 | | - |
68 | | --- Public function |
69 | | -function M.public_function() |
70 | | - -- implementation |
71 | | -end |
72 | | - |
73 | | -return M |
74 | | -``` |
75 | | - |
76 | | -### Conventions |
77 | | - |
78 | | -- **Imports:** Group at top: `local git = require("utils.git")` |
79 | | -- **Functions:** `snake_case` - `function M.word_wrap()`, `local function get_terminal_width()` |
80 | | -- **Indentation:** 2 spaces, `expandtab`, `smartindent` |
81 | | -- **Error handling:** Guard clauses, nil checks: `if handle == nil then return nil end` |
82 | | -- **Keymaps:** Use `require("utils").set_keymap()` NOT `vim.keymap.set()` directly |
83 | | - - Signature: `set_keymap(mode, lhs, rhs, opts_or_desc)` |
84 | | - - Provides defaults: `noremap = true, silent = true` |
85 | | -- **User commands:** Use `require("utils").set_usrcmd()` NOT `vim.api.nvim_create_user_command()` |
86 | | - |
87 | | -### Plugin Structure (Lazy.nvim) |
88 | | - |
89 | | -- Files in `.config/nvim/lua/plugins/{category}/` return table(s) with plugin specs |
90 | | -- Categories: `ai/`, `core/`, `lang/`, `misc/`, `ui/`, `workflow/` |
91 | | -- Example spec: |
92 | | - |
93 | | -```lua |
94 | | -return { |
95 | | - { |
96 | | - "author/plugin-name", |
97 | | - dependencies = { "other/plugin" }, |
98 | | - event = "VeryLazy", -- or cmd, keys, ft, etc. |
99 | | - config = function() |
100 | | - require("plugin-name").setup({ ... }) |
101 | | - end, |
102 | | - }, |
103 | | -} |
104 | | -``` |
105 | | - |
106 | | -## 🐟 Fish Shell Style |
107 | | - |
108 | | -- **Abbreviations:** Prefer `abbr` over `alias` for shell expansion (e.g., `abbr n nvim`) |
109 | | -- **Functions:** Use for complex logic, `snake_case` naming |
110 | | -- **Conditionals:** `switch/case` for platform detection |
111 | | -- **Cross-platform compatibility:** Terminal emulator and shell scripts should work across macOS, Linux, and BSD unless otherwise specified |
112 | | - - Use `switch (uname)` to handle platform-specific behavior |
113 | | - - Test for command availability with `command -v` before using platform-specific tools |
114 | | - - Prefer standard POSIX utilities when possible |
115 | | - |
116 | | -## 📂 File Organization |
117 | | - |
118 | | -``` |
119 | | -.config/{app}/ # App-specific configs |
120 | | -.config/nvim/ |
121 | | - lua/ |
122 | | - config/ # Core nvim config (opts, keymaps, autocmd, etc.) |
123 | | - keymaps/{category}/ # Organized keybindings |
124 | | - hls/ # Highlight groups |
125 | | - plugins/{category}/ # Lazy.nvim plugin specs by category |
126 | | - utils/ # Reusable utility modules (git, format, fn, etc.) |
127 | | - snippets/ # Snippet files |
128 | | - spell/ # Custom spellcheck dictionaries |
129 | | -.config/fish/ |
130 | | - config.fish # Main config (sources other files) |
131 | | - aliases.fish # Aliases and abbreviations |
132 | | - profile.fish # Environment variables |
133 | | - scripts.fish # Helper functions |
134 | | -.config/vicinae/extensions/ # Custom Vicinae extensions (see AGENTS.md in this dir) |
135 | | -scripts/ # Repo maintenance scripts (ignored by stow) |
136 | | -Brewfile # All Homebrew dependencies |
137 | | -``` |
138 | | - |
139 | | -## 🎨 Theme & Consistency |
140 | | - |
141 | | -- **Colorscheme:** Zenwritten Dark everywhere |
142 | | -- **Fonts:** Zenbones Brainy, JetBrains Mono, BabelStone Runic, Symbols Nerd Font |
143 | | -- When modifying themes: Update `.config/{nvim,wezterm,bat,opencode,rofi,waybar,etc.}` |
144 | | - |
145 | | -## 🖥️ Platform-Specific Notes |
146 | | - |
147 | | -- Check platform: `require("utils.platform")` in Lua, `switch (uname)` in Fish |
148 | | -- **macOS (Darwin):** Uses Homebrew from `/opt/homebrew` or `/usr/local` |
149 | | -- **Linux:** May use Homebrew from `/home/linuxbrew/.linuxbrew` or native package managers |
150 | | -- **Cursor/VSCode:** Fish auto-switches to dash (see `.config/fish/config.fish:1-4`) |
151 | | - |
152 | | -## 🚫 Git Commit Policy |
153 | | - |
154 | | -**NEVER commit changes unless explicitly asked by the user.** |
155 | | - |
156 | | -- You may stage files for review (`git add`) if the user asks to see what would be committed |
157 | | -- You may show diffs and suggest commit messages |
158 | | -- You may prepare changes and inform the user they are ready to commit |
159 | | -- But ONLY create commits when the user explicitly requests it with commands like "commit this", "make a commit", etc. |
160 | | - |
161 | | -## 🧪 Validation Checklist |
162 | | - |
163 | | -Before committing config changes: |
164 | | - |
165 | | -1. [ ] Run `stow -n .` to preview symlink changes |
166 | | -2. [ ] Test Neovim: `nvim --headless +checkhealth +qa` |
167 | | -3. [ ] Test Fish: `fish -c "source ~/.config/fish/config.fish"` |
168 | | -4. [ ] Verify no auto-generated files are staged: `git status` |
169 | | -5. [ ] Check `.gitignore` patterns match |
| 3 | +Personal dotfiles managed with GNU Stow for symlink management across macOS and Linux. |
| 4 | + |
| 5 | +## Essentials |
| 6 | + |
| 7 | +- Do not edit auto-generated files: |
| 8 | + - `lazy-lock.json` (Lazy.nvim lockfile) |
| 9 | + - `Brewfile.lock.json` (Homebrew lockfile) |
| 10 | + - `.config/nvim/.sessions/`, `.config/nvim/.undo/`, `.config/nvim/.backup/` (Neovim state) |
| 11 | + - `.config/fish/{fish_variables,completions,conf.d,functions}/` (Fish shell state) |
| 12 | + - `.config/lazygit/state.yml` (Lazygit state) |
| 13 | + - `.config/ags/@girs/` (AGS TypeScript type definitions; regenerate with `ags types`) |
| 14 | +- Package manager: Homebrew via `brew bundle install`. |
| 15 | + |
| 16 | +## More Guidance |
| 17 | + |
| 18 | +- [Common operations](docs/agents/operations.md) |
| 19 | +- [Neovim Lua style](docs/agents/nvim-lua.md) |
| 20 | +- [Fish shell style](docs/agents/fish-shell.md) |
| 21 | +- [File organization](docs/agents/file-organization.md) |
| 22 | +- [Theme and consistency](docs/agents/theme.md) |
| 23 | +- [Platform notes](docs/agents/platform.md) |
| 24 | +- [Git workflow and validation](docs/agents/git-workflow.md) |
0 commit comments