diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3dca762
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,32 @@
+# Owlry - Claude Code Instructions
+
+## Release Workflow
+
+Always use `just` for releases and AUR deployment:
+
+```bash
+# Bump version (updates Cargo.toml + Cargo.lock, commits)
+just bump 0.x.y
+
+# Push and create tag
+git push && just tag
+
+# Update AUR package
+just aur-update
+
+# Review changes, then publish
+just aur-publish
+```
+
+Do NOT manually edit Cargo.toml for version bumps - use `just bump`.
+
+## Available just recipes
+
+- `just build` / `just release` - Build debug/release
+- `just check` - Run cargo check + clippy
+- `just test` - Run tests
+- `just bump <version>` - Bump version
+- `just tag` - Create and push git tag
+- `just aur-update` - Update PKGBUILD checksums
+- `just aur-publish` - Commit and push to AUR
+- `just aur-test` - Test PKGBUILD locally
diff --git a/config.example.toml b/config.example.toml
new file mode 100644
index 0000000..1be1e74
--- /dev/null
+++ b/config.example.toml
@@ -0,0 +1,42 @@
+# Owlry Configuration
+# Copy to ~/.config/owlry/config.toml
+
+[general]
+show_icons = true
+max_results = 10
+terminal_command = "kitty"  # Auto-detected if not set
+
+# Launch wrapper for app execution (auto-detected if not set)
+# Examples:
+#   "uwsm app --"              # For uwsm sessions
+#   "hyprctl dispatch exec --" # For Hyprland
+#   ""                         # Direct execution
+# launch_wrapper = "uwsm app --"
+
+[appearance]
+width = 600
+height = 400
+font_size = 14
+border_radius = 12
+
+# Theme: "owl" for built-in dark theme, or leave unset for GTK default
+# theme = "owl"
+
+# Individual color overrides (CSS color values)
+# [appearance.colors]
+# background = "#1a1b26"
+# background_secondary = "#24283b"
+# border = "#414868"
+# text = "#c0caf5"
+# text_secondary = "#565f89"
+# accent = "#7aa2f7"
+# accent_bright = "#89b4fa"
+# badge_app = "#9ece6a"
+# badge_cmd = "#7aa2f7"
+# badge_dmenu = "#bb9af7"
+# badge_uuctl = "#f7768e"
+
+[providers]
+applications = true
+commands = true
+uuctl = true