# Dotfiles Knowledge

## Project Purpose

Personal dotfiles for `alex` on a Linux/Wayland desktop. Managed as a bare or normal git repo in `~/dotfiles/`. Covers the full desktop stack: shell, editor, compositor, terminal, status bar, notifications, and AI tooling.

## Repository Layout

```
~/dotfiles/
├── .bash_profile / .bashrc / .zshrc / .profile   # Legacy/fallback shell configs
├── .gitconfig                                      # Git global config (gh credential helper)
├── .ssh/                                           # SSH keys and known_hosts
└── .config/
    ├── dunst/          # Notification daemon
    ├── fish/           # Primary shell
    ├── hypr/           # Wayland compositor + screen lock
    ├── kitty/          # Terminal emulator
    ├── nvim/           # Editor (Neovim)
    ├── opencode/       # AI coding assistant (complex subsystem)
    ├── rofi/           # App launcher
    ├── waybar/         # Status bar
    └── zathura/        # PDF viewer
```

## Desktop Stack

| Layer | Tool | Notes |
|---|---|---|
| Compositor | Hyprland | Wayland, tiling, dwindle layout |
| Terminal | Kitty | GPU-accelerated |
| Shell | Fish | Primary shell |
| Editor | Neovim | lazy.nvim plugin manager |
| Status bar | Waybar | Bottom layer, top position |
| App launcher | Rofi | `rofi -show drun` |
| Notifications | Dunst | |
| Screen lock | Hyprlock | `SUPER+C` |
| Screenshots | Hyprshot | Print=region, Shift+Print=output |
| File manager | Thunar | |
| Browser | Brave | `SUPER+B` / `SUPER+SHIFT+B` incognito |
| Email | Thunderbird | `SUPER+M` |
| VPN | ProtonVPN | Auto-started via hyprland exec-once |
| Mail bridge | Protonmail Bridge | Auto-started `--no-window` |
| PDF viewer | Zathura | |

## Hyprland Configuration

File: `.config/hypr/hyprland.conf`

- **mainMod:** SUPER (`caps:super` — Caps Lock acts as Super)
- **Layout:** dwindle (no gaps, border_size=1, rounding=10)
- **Keyboard:** `us, br` layouts; `alts_toggle` (Alt+Shift switches layout)
- **Animations:** disabled
- **Autostart:** waybar, nm-applet, protonmail-bridge --no-window, protonvpn-app

### Key Bindings
```
SUPER+Return    kitty
SUPER+Q         kill window
SUPER+E         thunar
SUPER+Space     rofi
SUPER+F         fullscreen
SUPER+B/Shift+B brave / brave --incognito
SUPER+M         thunderbird
SUPER+V         protonvpn-app
SUPER+C         hyprlock
Print           hyprshot -m region
Shift+Print     hyprshot -m output
SUPER+h/j/k/l   move focus (vim dirs)
SUPER+SHIFT+h/j/k/l  move window
SUPER+1-9/0     switch workspace
SUPER+SHIFT+1-9/0    move to workspace
SUPER+S         scratchpad toggle
SUPER+R         resize submap (h/j/k/l = 30px steps)
```

## Theme: Catppuccin Mocha

Applied uniformly across all tools:

| Tool | Config file |
|---|---|
| Hyprland borders | `hyprland.conf` (lavender→mauve active, surface0 inactive) |
| Kitty | `kitty/kitty.conf` (full 16-color palette) |
| Neovim | `nvim/lua/plugins/colorscheme.lua` (catppuccin/nvim, flavour=mocha) |
| Fish | `fish/config.fish` (Catppuccin Mocha theme via fish_config) |
| Fish plugin | `fish/fish_plugins` (catppuccin/fish installed via fisher) |

Key colors: bg=#1e1e2e, fg=#cdd6f4, lavender=#b4befe, mauve=#cba6f7, crust=#11111b, surface0=#313244

## Shell: Fish

Files: `.config/fish/`

- **Plugin manager:** fisher (jorgebucaran/fisher)
- **Plugins:** catppuccin/fish
- **Theme:** Catppuccin Mocha (set in config.fish)

### Functions / Aliases
| Function | Expands to | Purpose |
|---|---|---|
| `c` | `opencode` | Launch OpenCode AI assistant |
| `cc` | `opencode --continue` | Continue last OpenCode session |
| `co` | `copilot` | GitHub Copilot CLI |
| `n` | `nvim` | Neovim |

## Editor: Neovim

Files: `.config/nvim/`

- **Entry:** `init.lua` — sets `mapleader=<Space>`, bootstraps lazy.nvim
- **Plugins:** all in `lua/plugins/`, auto-loaded via `{ import = 'plugins' }`
- **Options:** `number=true`, `relativenumber=true`, `wrap=false`

### Plugin List

| Plugin | File | Purpose |
|---|---|---|
| catppuccin/nvim | colorscheme.lua | Mocha colorscheme, priority=1000 |
| nvim-cmp | cmp.lua | Completion engine |
| stevearc/conform.nvim | conform.lua | Format on save |
| folke/lazydev | lazydev.lua | Neovim Lua dev assistance |
| neovim/nvim-lspconfig | lspconfig.lua | LSP client config |
| L3MON4D3/LuaSnip | luasnip.lua | Snippet engine |
| williamboman/mason.nvim | mason.lua | LSP/tool installer UI |
| mason-lspconfig.nvim | mason-lspconfig.lua | Mason+LSP bridge, auto-install |
| jay-babu/mason-null-ls | mason-null-ls.lua | Mason+null-ls bridge |
| nvimtools/none-ls | none-ls.lua | LSP diagnostics from external tools |
| opencode-ai/nvim-opencode | opencode.lua | OpenCode integration |
| nvim-telescope/telescope | telescope.lua | Fuzzy finder |
| nvim-treesitter | treesitter.lua | Syntax parsing |

### Keymaps
```
<leader>e       vim.cmd.Ex (file explorer)
<leader>ww      save file
<leader>ff      Telescope find_files
<leader>fg      Telescope live_grep
<leader>fb      Telescope buffers
<leader>fh      Telescope help_tags
<leader>f       Conform format (async)
```

### LSP / Formatting
- **mason-lspconfig:** `automatic_installation=true`, `automatic_enable=true`; injects `cmp_nvim_lsp` capabilities to all LSP servers globally
- **conform formatters by filetype:**
  - lua → stylua
  - js/ts/jsx/tsx/json/yaml/md → prettier
  - python → ruff_format
  - go → gofmt
- **format_on_save:** timeout_ms=500, lsp_fallback=true
- **Diagnostics:** virtual_text, signs, underline; float border=rounded, source=always

## Status Bar: Waybar

File: `.config/waybar/config` + `style.css` + `scripts/pomodoro-preset.sh`

- Layer: bottom, position: top, spacing: 6
- **Left:** backlight, wireplumber, custom/pomodoro
- **Center:** clock (`{:%H:%M - %a,%d}`, interval=1)
- **Right:** tray, bluetooth, temperature, cpu, memory, battery
- **Pomodoro:** external `waybar-module-pomodoro` binary; left=toggle, right=preset script, middle=reset
- **Custom/music:** playerctl metadata polling (interval=5)
- CPU click: `ghostty -e htop` (note: Ghostty not Kitty here)
- Bluetooth click: blueman-manager

## OpenCode AI System

Files: `.config/opencode/`

The most complex subsystem. Full multi-agent AI coding assistant configuration.
See [OpenCode Architecture](research/opencode-architecture.md) for detailed breakdown.

**Quick reference:**
- Config: `opencode.jsonc` (default_agent=lead, plugin=@tarquinen/opencode-dcp)
- Agents: `agents/*.md` (10 agents: lead, coder, reviewer, tester, explorer, researcher, librarian, critic, sme, designer)
- Memory: `agents/.memory/` — persistent knowledge for the AI system itself
- Instruction files: `.github/copilot-instructions.md` (canonical), `CLAUDE.md` + `.cursorrules` (symlinks); `AGENTS.md` is NOT a symlink (global OpenCode config)
- MCP servers: context7 (remote docs), gh_grep (remote code search), playwright (local Chromium)
- Skills: `skills/doc-coverage/`, `skills/git-workflow/`, `skills/work-decomposition/`

## Git Configuration

File: `.gitconfig`

- `user.name=alex`, `user.email=misc@wiesner.com.br`
- `init.defaultBranch=main`
- Credential helper: `!/usr/bin/gh auth git-credential` (GitHub + Gist)