From fa02adb59fde46921a965f62208cd7eaee6a82c6 Mon Sep 17 00:00:00 2001
From: mwiegand <martin.wiegand@seibert.group>
Date: Sun, 19 Apr 2026 16:06:54 +0200
Subject: [PATCH] docs: add repo usage and agent guidance

---
 AGENTS.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 104 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 README.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..90ff093
--- /dev/null
+++ b/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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ef2afcb
--- /dev/null
+++ b/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