docs: add repo usage and agent guidance

AGENTS.md

@@ -0,0 +1,48 @@
+# Agent Instructions
+
+## Scope
+
+This repo currently contains only shared zsh UI config.
+
+Source of truth:
+- `./.zshrc`
+
+## Boundaries
+
+Do not move machine-specific shell config into this repo unless explicitly requested.
+
+Assume local `~/.zshrc` remains machine-specific and only bootstraps this repo with:
+
+```zsh
+source "$HOME/Projekte/dotfiles/.zshrc"
+```
+
+## Change Style
+
+Keep changes minimal.
+
+Prefer small, focused improvements to shared shell UX:
+- prompt
+- history behavior
+- autosuggestions
+- key bindings
+
+Do not add frameworks or broad shell refactors unless explicitly requested.
+
+## Verification
+
+Before claiming success, run:
+
+```bash
+zsh -n .zshrc
+```
+
+For behavior checks, use a fresh interactive shell:
+
+```bash
+zsh -i -c 'true; precmd; print -P -- "$PROMPT"'
+```
+
+## Git
+
+Use Conventional Commits.

README.md

@@ -0,0 +1,56 @@
+# dotfiles
+
+Shared shell configuration.
+
+## Scope
+
+This repo currently tracks only shared zsh UI behavior.
+
+Tracked file:
+- `.zshrc`
+
+This repo is intentionally small. Machine-specific shell setup stays in the local `~/.zshrc` unless explicitly promoted into shared config later.
+
+## Local Setup
+
+Local `~/.zshrc` is expected to source this repo-managed file:
+
+```zsh
+source "$HOME/Projekte/dotfiles/.zshrc"
+```
+
+That keeps the repo as the source of truth for shared prompt and shell UX, while local environment setup can remain machine-specific.
+
+## What Lives Here
+
+Current shared config includes:
+- prompt styling
+- git branch display in the prompt
+- exit-code based prompt arrow color
+- zsh autosuggestions
+- prefix-based history search on arrow keys
+
+## Verification
+
+Syntax check:
+
+```bash
+zsh -n ~/.zshrc
+zsh -n ~/Projekte/dotfiles/.zshrc
+```
+
+Quick interactive prompt check:
+
+```bash
+zsh -i -c 'true; precmd; print -P -- "$PROMPT"'
+```
+
+## Notes
+
+Keep this repo focused on shared interactive shell UX.
+
+Examples of config that should usually stay local:
+- secrets
+- host-specific paths
+- machine-specific SDK setup
+- one-off helper functions