diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..435e720
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,86 @@
+# 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 tests, CI or build scripts – the repo is purely configuration data.
+- The only executable content is the `install_*` shell scripts that install system packages.
+
+---
+## 2. System Setup
+
+| Task | Command | Why it matters |
+|------|---------|----------------|
+| **Install required programs** | `bash .install_skripte/install_terminal_pcks.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. |
+| **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**
\ No newline at end of file