# OpenCode Agent Reference – Dotfiles Repository

This file contains the minimal, high‑signal instructions that an OpenCode agent should know before working in this repository.
Only entries that would be missed without explicit help are included.

---
## 1. Project Scope

- **Dotfiles** for a personal workstation (hyprland + Neovim + VST plugin).
- No CI or build scripts – the repo is purely configuration data; the only executable content is the `install_*` scripts and the `test/` harness.
- **Testing** lives in `test/`. `make test` runs the offline lint plus the Docker smoke with the real pacman install (`REAL_SMOKE=1`); `make test-lint` / `make test-stow` are the fast offline subset, and `make test-smoke REAL_SMOKE=0` runs dry probes only (see `test/Dockerfile` and `README.md → Testing`).

---
## 2. System Setup

| Task | Command | Why it matters |
|------|---------|----------------|
| **Install required programs** | `bash term/setup.sh` <br>`bash _install_skripte/install_basic_pcks.sh` <br>`bash _install_skripte/install_hypr_pcks.sh` <br>`bash _install_skripte/install_kreation_pcks.sh` | These scripts install Neovim, hyprland, VST runtime, and other utilities. Edit `term/packages.txt` to add/remove terminal packages. |
| **Link configuration directories** | `ln -s ~/.dotfiles/hypr/.config/hypr ~/.config/hypr` <br>`ln -s ~/.dotfiles/term/.config/nvim ~/.config/nvim` | The repository expects the configs to live in `~/.config`. |
| **Add VST plugin** | Copy `kreation/.vst3/MT-PowerDrumKit.vst3` into your DAW’s plugins folder (usually `~/.vst`). | The repo contains a pre‑built VST for use in audio software. |

> *If you skip any of these steps, hyprland will not start or Neovim will fail to load its plugins.*

---
## 3. Hyprland Specifics

| Item | Detail |
|------|--------|
| **Wayland compositor** | Requires `hyprland` (and dependencies like `wlroots`). The script `install_hypr_pcks.sh` installs it. |
| **MIME defaults** | Run `bash hypr/.config/hypr/scripts/ensure-env.sh` after installing to set environment variables (`$XDG_DATA_HOME`, etc.). |
| **Dolphin file associations** | `bash hypr/.config/hypr/scripts/fix_dolphin_file_associations.sh` must be executed once to register the compositor with KDE. |
| **Portal host override** | `bash hypr/.config/hypr/scripts/portal-host-override.sh` fixes Wayland portal issues on some distros. |

> *Agents should remember to run the above scripts when setting up a fresh machine.*

---
## 4. Neovim Specifics

| Item | Detail |
|------|--------|
| **Neovim version** | Requires ≥ 0.10. The init.lua bootstraps `lazy.nvim` automatically. |
| **Node.js for LSP/TS plugins** | `fnm` is used to set the PATH. Ensure `fnm current` returns a valid node version; otherwise install fnm from https://github.com/jdx/mason. |
| **Python tooling** | After cloning, run:  
```bash
pip install debugpy ruff black
```
These are used by the LSP and formatter plugins. |
| **Lazy.nvim plugin load** | Plugins are listed under `term/.config/nvim/plugins`. They will be installed automatically on first launch. |
| **Keymaps** | Basic `<leader>w/q`, LSP (`gd/gD/gi/gr/K`) and window navigation (`<C-h/j/k/l>`) are pre‑configured. |

> *If any plugin fails to load, check that the required language server is installed (e.g., `pyright` for Python).*

---
## 5. OpenCode Configuration

| Key | Value |
|-----|-------|
| **default_agent** | `plan` – the agent starts in planning mode. |
| **provider.lmstudio** | Uses local LM Studio with Gemma and Mistral models. |
| **permissions** | Bash, read, glob, grep are allowed; write/edit are *ask*. |
| **experimental.lsp** | Enabled – agents can query Neovim LSP via `lsp` tool. |

> *Agents should not attempt to modify files unless the user explicitly allows it.*

---
## 6. Typical Workflow for a New Setup

1. **Clone repo**  
```bash
git clone https://github.com/<user>/dotfiles.git ~/.dotfiles
```
2. **Run install scripts** (as root or with sudo if required).  
3. **Link configs** (`ln -s …`) as shown above.  
4. **Start hyprland** from a login manager or by running `hyprland`.  
5. **Open Neovim** – it will bootstrap plugins automatically.  

---
## 7. Things to Watch Out For

- The repository contains *binary* VST files; do not delete the `.vst3` folder.
- Scripts assume you have `bash`, `git`, and `curl`.
- Path modifications for `fnm` only apply in the current shell session; you may want to add them to your shell profile.
- If you switch to a different compositor, remember to run `ensure-env.sh` again.

---
**End of AGENTS.md**