diff --git a/CLAUDE.md b/CLAUDE.md
index 1285f44..f22b9eb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,6 +28,7 @@ When a topic comes up, load `{tech}/CONTEXT.md` + `{tech}/troubleshooting.md`. F
 | server config, gitea config, infrastructure | `server-configs/` |
 | database, postgres, redis, sql | `databases/` |
 | backup, restic, snapshot, restore, retention | `backups/` |
+| workstation, dotfiles, symlink, fish, starship, mangohud, zed | `workstation/` |
 
 **Special loads:**
 - Pi-hole → also `networking/pihole-ha-setup.md`
diff --git a/workstation/CONTEXT.md b/workstation/CONTEXT.md
new file mode 100644
index 0000000..a9686de
--- /dev/null
+++ b/workstation/CONTEXT.md
@@ -0,0 +1,54 @@
+# Workstation Configuration
+
+## Dotfiles Repository
+
+- **Repo**: `cal/dotfiles` (private) on `git.manticorum.com`
+- **Local path**: `~/dotfiles/`
+- **Strategy**: Symlink — configs live in the repo, symlinked to their expected system paths
+
+### What's tracked
+
+| Category | Repo path | System path |
+|----------|-----------|-------------|
+| Fish shell | `fish/config.fish` | `~/.config/fish/config.fish` |
+| Starship prompt | `starship.toml` | `~/.config/starship.toml` |
+| Git config | `git/.gitconfig` | `~/.gitconfig` |
+| Git global ignore | `git/ignore` | `~/.config/git/ignore` |
+| SSH config | `ssh/config` | `~/.ssh/config` |
+| Bash | `shell/.bashrc`, `shell/.bash_profile` | `~/.bashrc`, `~/.bash_profile` |
+| Zsh | `shell/.zshrc`, `shell/.zshenv` | `~/.zshrc`, `~/.zshenv` |
+| MangoHud | `mangohud/MangoHud.conf` | `~/.config/MangoHud/MangoHud.conf` |
+| Zed editor | `zed/settings.json` | `~/.config/zed/settings.json` |
+| Restic excludes | `restic/excludes.txt` | `~/.config/restic/excludes.txt` |
+| VS Code | `vscode/settings.json`, `vscode/keybindings.json` | `~/.config/Code/User/` |
+
+### Secrets handling
+
+API keys and tokens are **never** committed. Shell configs source secrets from separate untracked files:
+- Bash: `~/.bash_secrets` (chmod 600)
+- Zsh: `~/.zsh_secrets`
+
+### Install / Uninstall
+
+```bash
+cd ~/dotfiles
+./install.sh    # Backs up originals to ~/.dotfiles-backup/, creates symlinks
+./uninstall.sh  # Replaces symlinks with standalone copies
+```
+
+Both scripts are idempotent.
+
+### Adding a new config
+
+1. Copy the file into the appropriate directory in `~/dotfiles/`
+2. Add the mapping to the `LINKS` associative array in both `install.sh` and `uninstall.sh`
+3. Run `./install.sh` to replace the original with a symlink
+4. Commit and push
+
+### Shell setup
+
+Cal migrated from zsh to **fish + starship** (Feb 2026). Bash and zsh configs are retained for compatibility but fish is the primary interactive shell.
+
+## Backups
+
+Original files are backed up by `install.sh` to `~/.dotfiles-backup/<timestamp>/` before being replaced with symlinks. Multiple runs create separate timestamped backup dirs. Old backups can be cleaned up manually.