diff --git a/CLAUDE.md b/CLAUDE.md
index 290b94b..f96a276 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,12 @@
 - On interrupt: stop immediately, commit partial work, then reassess
 - After any file edit, re-read before editing again (stale context kills diffs)
 
+## Environment
+
+Primary terminal stack: **Ghostty + fish + zellij**.
+Fish is the first-class shell — all interactive config lives under `home/.config/fish/`.
+`rc.common` / `rc.bash` / `rc.zsh` exist for POSIX/bash compat but are secondary.
+
 ## Ownership
 
 - `setup/` — setup scripts; each file is one concern (packages, python, node, etc.)
@@ -13,7 +19,9 @@
 - `home/` — homeshick-managed dotfiles (symlinked into `~`)
 - `home/.config/nvim/` — LazyVim configuration
 - `home/.config/fish/` — fish shell config and functions
+- `home/.config/fish/conf.d/` — auto-sourced fish snippets (env vars, aliases per tool)
 - `home/.config/ghostty/` — Ghostty terminal config + shaders
+- `home/.config/rg/config` — ripgrep defaults (loaded via RIPGREP_CONFIG_PATH)
 - `rc.common`, `rc.bash`, `rc.zsh` — shell init; `rc.common` is the shared core
 - `getaround.sh` — shell framework (EDITOR, keybindings, helpers)
 - `aliases`, `functions` — shell aliases and functions
diff --git a/README.md b/README.md
index 404b022..75f47f3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,61 @@
 # dotfiles
 
 These are my dotfiles.
+
+Primary terminal stack: **Ghostty + fish + zellij**.
+Fish is the first-class interactive shell; all interactive config lives under
+`home/.config/fish/`. The `rc.common` / `rc.bash` / `rc.zsh` files exist for
+POSIX/bash compatibility but are secondary.
+
+---
+
+## Search tools (fd / rg)
+
+Both tools are configured to behave well inside git repos where `.gitignore`
+is often overly restrictive (generated configs, editor files, etc.).
+
+### What's configured
+
+| Setting | fd | rg |
+|---|---|---|
+| Include hidden files | `--hidden` | `--hidden` |
+| Ignore VCS ignore rules | `--no-ignore-vcs` | `--no-ignore-vcs` |
+| Exclude noise dirs | `--exclude <dir>` (× 6) | `--glob=!<dir>` (× 6) |
+
+**Excluded dirs:** `node_modules`, `dist`, `.git`, `target`, `__pycache__`, `.cache`
+
+**Why `--no-ignore-vcs`?** Inside a repo, generated configs, editor files, and
+local build artifacts are often gitignored. Without this flag both tools silently
+skip them, making searches feel broken. The explicit excludes above cover the dirs
+you almost never want.
+
+### Files
+
+- `home/.config/fish/conf.d/search.fish` — sets `RIPGREP_CONFIG_PATH` and the
+  `fd` alias.
+- `home/.config/rg/config` — ripgrep flags, loaded automatically via
+  `RIPGREP_CONFIG_PATH`.
+
+### Temporarily overriding
+
+```fish
+# Nuclear: respect nothing, search everything
+fd --no-ignore --no-ignore-vcs <pattern>
+rg --no-ignore --no-ignore-vcs <pattern>
+
+# Add back a single ignore file (e.g. a local .ignore)
+fd --ignore-file .ignore <pattern>
+
+# One-off: also search node_modules
+fd --no-ignore-vcs <pattern>   # removes the alias excludes automatically
+```
+
+> `fd` alias flags are baked into the function; to skip the alias entirely use
+> `command fd <args>`.
+
+### Updating the exclude list
+
+Edit both files together so they stay in sync:
+
+1. `home/.config/fish/conf.d/search.fish` — add `--exclude <dir>` to the alias.
+2. `home/.config/rg/config` — add `--glob=!<dir>`.
diff --git a/home/.config/fish/conf.d/search.fish b/home/.config/fish/conf.d/search.fish
new file mode 100644
index 0000000..4c4e439
--- /dev/null
+++ b/home/.config/fish/conf.d/search.fish
@@ -0,0 +1,8 @@
+# Search tool defaults (fd + rg)
+# See README.md § "Search tools (fd / rg)" for rationale.
+
+# RIPGREP_CONFIG_PATH — picked up automatically by rg on every invocation
+set -gx RIPGREP_CONFIG_PATH "$HOME/.config/rg/config"
+
+# fd: hidden files, ignore VCS ignore rules, but skip common noise dirs
+alias fd='fd --hidden --no-ignore-vcs --exclude node_modules --exclude dist --exclude .git --exclude target --exclude __pycache__ --exclude .cache'
diff --git a/home/.config/rg/config b/home/.config/rg/config
new file mode 100644
index 0000000..bdf4034
--- /dev/null
+++ b/home/.config/rg/config
@@ -0,0 +1,16 @@
+# ripgrep defaults — loaded via RIPGREP_CONFIG_PATH
+# See README.md § "Search tools (fd / rg)" for rationale.
+
+# Include hidden files/dirs (e.g. .editorconfig, .env, .github/)
+--hidden
+
+# Don't honour .gitignore — too restrictive inside git repos
+--no-ignore-vcs
+
+# Skip common noise directories
+--glob=!node_modules
+--glob=!dist
+--glob=!.git
+--glob=!target
+--glob=!__pycache__
+--glob=!.cache