docs: add README documenting dotfiles by samuelreh · Pull Request #2 · samuelreh/dotfiles

samuelreh · 2026-02-25T14:59:33Z

Summary

Adds a comprehensive README.md documenting all dotfiles in the repository
Covers installation, shell (Zsh/Oh My Zsh) configuration, git aliases and settings, Neovim plugins and keybindings, and prerequisites
Resolves SAM-7

Test plan

Verify README renders correctly on GitHub
Confirm all documented files and settings match the actual repository contents

🤖 Generated with Claude Code

samuelreh · 2026-02-26T23:43:39Z

@iris can you review these changes please

samuelreh · 2026-02-26T23:45:08Z

@iris please respond

samuelreh · 2026-02-26T23:50:48Z

@iris please help

samuelreh · 2026-02-26T23:52:34Z

+
+Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.
+
+## Contents


@iris can you remove the contents section

samuelreh · 2026-02-27T00:04:31Z

+
+Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.
+
+## Contents


@iris can you remove the contents section here

samuelreh · 2026-02-27T00:13:46Z

+| `config/nvim/coc-settings.json` | CoC (Conquer of Completion) language server settings |
+| `install.sh` | Installation script that symlinks dotfiles into `$HOME` |
+
+## Installation


@iris can you remove this section

samuelreh · 2026-02-27T00:14:31Z

+
+Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.
+
+## Contents


@iris can you remove this section

samuelreh · 2026-02-27T13:59:02Z

+# Dotfiles
+
+Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.
+


@iris can we add a table of contents here

samuelreh · 2026-02-27T14:12:56Z

+Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.
+
+## Shell (Zsh)
+


@iris can you add a table of contents

iris-test-samr · 2026-02-27T14:18:10Z

👀 On it — working on this now.

samuelreh · 2026-02-27T21:11:03Z

@@ -0,0 +1,127 @@
+# Dotfiles
+
+Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.


@iris We've recently updated the dotfiles in this repo, can you update this PR to reflect the latests master

👀 On it — working on this now.

Documents all configuration files, installation process, shell setup, git aliases, Neovim plugins/keybindings, and prerequisites. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rewrites the README to accurately document the current dotfiles which have migrated from vim-plug/CoC to LazyVim/lazy.nvim. Adds sections for tmux and Ghostty configuration, updates Neovim plugin list, keymaps, and prerequisites. Updates shell section to reflect current zshrc (fzf, direnv, auto-tmux, wt wrapper). Resolves SAM-7 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iris-test-samr · 2026-02-27T21:15:14Z

✅ Iris Agent — completed

Done! I've updated the PR to reflect the latest master. Here's what changed in the README:

Major updates:

Neovim section — Rewritten from vim-plug/CoC-based setup to document the current LazyVim/lazy.nvim configuration with catppuccin theme, diffview, tmux-navigator, snacks picker, and rbenv-managed Ruby tools
Shell section — Updated to reflect current zshrc: removed old aliases (edit, today, find_and_replace) and Kubernetes helpers; added fzf integration, direnv, auto-tmux, and the wt worktree wrapper
New Tmux section — Documents the full tmux config (C-a prefix, vim-style navigation, catppuccin theme, TPM plugins, copy mode)
New Ghostty section — Documents the Ghostty terminal config (FiraCode Nerd Font, Catppuccin Mocha)
Git section — Added SSH signing via 1Password and Git LFS
Installation section — Documents what install.sh symlinks
Prerequisites — Updated to list current dependencies (LazyVim, Ghostty, tmux/TPM, fzf, direnv, 1Password, FiraCode Nerd Font)

PR: #2

samuelreh · 2026-02-27T21:23:42Z

+
+Personal dotfiles for macOS development environment. Manages shell, git, Neovim, tmux, and terminal configuration.
+
+## Table of Contents


@iris please remove the table of contents

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iris-test-samr · 2026-02-27T21:24:27Z

✅ Iris Agent — completed

Done — removed the Table of Contents section from the README and pushed the change to the PR branch.

samuelreh · 2026-02-27T23:14:53Z

+- **Theme:** Catppuccin Mocha
+- **macOS:** Option key acts as Alt
+
+## Prerequisites


@iris Can you create a coming soon / planned work section that makes reccomentations for additional plugins or configurations we should consider.

Add a "Planned Work" section to the README with curated recommendations for additional plugins and configurations across shell (zsh-autosuggestions, zsh-syntax-highlighting, zoxide, Starship), Neovim (treesitter-textobjects, flash.nvim, nvim-dap, copilot, todo-comments, trouble.nvim), tmux (resurrect, continuum, fzf), git (delta, git-absorb), and general tooling (Homebrew Bundle, mise). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iris-test-samr · 2026-02-27T23:16:48Z

✅ Iris Agent — completed

Done. I've added a Planned Work section to the README with recommendations organized by category:

Shell — zsh-autosuggestions, zsh-syntax-highlighting, zoxide, Starship
Neovim — treesitter-textobjects, flash.nvim, nvim-dap, copilot/codecompanion, todo-comments, trouble.nvim
Tmux — tmux-resurrect, tmux-continuum, tmux-fzf
Git — delta, git-absorb
General — Homebrew Bundle (Brewfile), mise (unified version manager to replace rbenv)

Each recommendation includes a brief explanation of what it does and why it complements the existing setup.

samuelreh

@iris can you implement these

samuelreh · 2026-02-27T23:21:48Z

+
+### General
+
+- **[Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle)** — Add a `Brewfile` to version-control all Homebrew dependencies (fzf, ripgrep, direnv, neovim, etc.) so the full environment can be reproduced with `brew bundle`.


oh I like this alot, can we add this to the PR

samuelreh · 2026-02-27T23:21:54Z

+- **[zoxide](https://github.com/ajeetdsouza/zoxide)** — Smarter `cd` that learns your most-visited directories. Much faster than typing full paths or using `cd -`.
+- **[Starship](https://starship.rs/)** — Cross-shell prompt with git status, language versions, and command duration built in. Could replace the custom Oh My Zsh prompt with richer info.
+
+### Neovim


One thing I'd really like a better plugin / workflow for is code review, right now I use nvim and then open diffview, which is nice as I can make edits in the diff, but it's kind of cumbersome to open it, what should I use instead? Or maybe I just need to add some bindings / command to open vim to diffview.

- Add zsh-autosuggestions and zsh-syntax-highlighting to Oh My Zsh plugins - Add zoxide for smarter directory navigation - Replace custom prompt with Starship cross-shell prompt - Add starship.toml config preserving the minimal cyan dir + yellow ✗ style with added git, language version, and command duration modules - Replace rbenv with mise in both zshrc and zprofile - Add starship config dir to install.sh symlinks Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Enable LazyVim extras: flash.nvim, todo-comments, trouble.nvim, nvim-dap (core), copilot, navic - Add nvim-treesitter-textobjects with select, move, and swap keymaps for functions, classes, and parameters - Update mason-ruby.lua to use mise shims instead of rbenv - Update options.lua PATH to use mise shims Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add tmux-resurrect and tmux-continuum for session save/restore - Add tmux-fzf for fuzzy-finding sessions, windows, and panes - Replace less with delta as git pager with side-by-side diffs, line numbers, and Catppuccin Mocha syntax theme - Add zdiff3 merge conflict style for clearer conflict markers - Add git-absorb alias for automatic fixup commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Includes all Homebrew dependencies: mise, neovim, tmux, fzf, ripgrep, direnv, starship, git-delta, git-absorb, zsh plugins, zoxide, language runtimes, fonts, and cask apps (Ghostty, 1Password). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Replace "Planned Work" section — all items are now implemented - Document Starship prompt, zsh-autosuggestions, zsh-syntax-highlighting, zoxide, mise, delta, git-absorb, treesitter-textobjects, flash.nvim, nvim-dap, copilot, todo-comments, trouble.nvim, tmux-resurrect, tmux-continuum, tmux-fzf, and Brewfile - Update all rbenv references to mise - Add Brewfile and brew bundle to installation instructions - Add treesitter text object keymaps to Neovim section - Update prerequisites to include new tools Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iris-test-samr · 2026-02-27T23:26:16Z

✅ Iris Agent — completed

All done. Here's a summary of the 5 commits pushed to the PR:

Shell (zshrc, zprofile, starship.toml, install.sh):

Added zsh-autosuggestions and zsh-syntax-highlighting to Oh My Zsh plugins
Added zoxide for smarter directory navigation (z command)
Replaced the custom prompt with Starship (with a config preserving the minimal style + git/language/duration modules)
Replaced rbenv with mise as the unified runtime version manager

Neovim (lazyvim.json, treesitter-textobjects.lua, mason-ruby.lua, options.lua):

Enabled LazyVim extras: flash.nvim, todo-comments, trouble.nvim, nvim-dap (core), copilot, navic
Added nvim-treesitter-textobjects with select/move/swap keymaps for functions, classes, and parameters
Updated all Ruby tooling paths from rbenv to mise shims

Tmux (tmux.conf):

Added tmux-resurrect + tmux-continuum for automatic session persistence
Added tmux-fzf for fuzzy-finding sessions/windows/panes

Git (gitconfig):

Replaced less with delta as pager (side-by-side diffs, line numbers, Catppuccin Mocha theme)
Added zdiff3 merge conflict style
Added absorb alias for git-absorb

General:

Created Brewfile with all Homebrew dependencies
Updated README.md — removed the "Planned Work" section (everything is implemented) and documented all new tools

samuelreh

@iris please address these comments

samuelreh · 2026-02-27T23:36:41Z

+| stevearc/conform.nvim | Formatting (rubocop via mise) |
+| mfussenegger/nvim-lint | Linting (rubocop, erb_lint via mise) |
+
+**Disabled plugins:** `noice.nvim` (to fix `:!` command escape codes), `telescope.nvim` (replaced by snacks picker)


If it's disabled can we just get rid of it

…commendations - Remove the "Disabled plugins" line per review feedback - Add Planned Work section with code review workflow improvements: shell alias for quick PR review, octo.nvim for in-editor GitHub PR reviews, and gh-dash as a terminal PR dashboard Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

iris-test-samr · 2026-02-27T23:39:05Z

✅ Iris Agent — completed

Done. I've addressed the two outstanding review comments:

Removed the "Disabled plugins" line — Per the comment "If it's disabled can we just get rid of it", I removed the **Disabled plugins:** noice.nvim ..., telescope.nvim ... line from the Neovim section.
Added a Planned Work section with code review workflow recommendations — Per the comment about wanting a better code review workflow than manually opening nvim + diffview, I added three concrete recommendations:
- A shell alias (review()) to jump straight into a diffview session from the terminal
- octo.nvim for full GitHub PR review inside Neovim (comments, approvals, merging)
- gh-dash as a terminal dashboard to browse PRs and launch into review

Changes pushed to the PR: #2

samuelreh

@iris please action on this

samuelreh · 2026-02-27T23:50:31Z

+brew "ripgrep"        # Fast grep (used by Neovim pickers)
+brew "direnv"         # Per-directory environment variables
+brew "git-lfs"        # Git Large File Storage
+brew "starship"       # Cross-shell prompt


so, I don't actually think I want starship, I'm good with the minimal ZSH provided prompt

User prefers the minimal ZSH prompt over Starship. Removes starship from zshrc, Brewfile, install.sh, config directory, README, and prerequisites. Restores the original custom PROMPT line. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

samuelreh

@iris please action on this

samuelreh · 2026-02-27T23:58:24Z

+brew "ripgrep"        # Fast grep (used by Neovim pickers)
+brew "direnv"         # Per-directory environment variables
+brew "git-lfs"        # Git Large File Storage
+brew "starship"       # Cross-shell prompt


so, I don't actually think I want starship, I'm good with the minimal ZSH provided prompt

iris-test-samr · 2026-02-28T00:00:53Z

✅ Iris Agent — completed

The latest commit has been pushed. Here's what was done:

Pushed commit 41ae26f — refactor: remove Starship prompt, restore minimal ZSH prompt

This commit addresses the review feedback ("I don't actually think I want starship, I'm good with the minimal ZSH provided prompt") by:

Removing starship from Brewfile
Removing starship from install.sh config dirs
Removing config/starship/starship.toml entirely
Restoring the minimal ZSH prompt (PROMPT='%F{cyan}%1~%f %B%F{yellow}✗%f%b ') in zshrc
Updating README.md to reflect the minimal custom prompt instead of Starship, and removing Starship from prerequisites

I also verified the entire README against the actual dotfiles — everything is accurate and up to date.

PR: #2

samuelreh commented Feb 26, 2026

View reviewed changes

samuelreh commented Feb 27, 2026

View reviewed changes

samuelreh and others added 5 commits February 27, 2026 13:11

docs: add comprehensive README documenting dotfiles

f989028

Documents all configuration files, installation process, shell setup, git aliases, Neovim plugins/keybindings, and prerequisites. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: remove Contents section from README

71febc4

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: remove Contents and Installation sections from README

0dbb43a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs: add table of contents to README

3c2422f

samuelreh force-pushed the iris/samuelreh/SAM-7 branch from d50fbe5 to 084e358 Compare February 27, 2026 21:15

samuelreh commented Feb 27, 2026

View reviewed changes

docs: remove table of contents from README

4dec360

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

samuelreh commented Feb 27, 2026

View reviewed changes

samuelreh and others added 5 commits February 27, 2026 15:23

samuelreh commented Feb 27, 2026

View reviewed changes


		Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.

		## Contents

		# Dotfiles

		Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.

		Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.

		## Shell (Zsh)

		@@ -0,0 +1,127 @@
		# Dotfiles

		Personal dotfiles for macOS development environment. Manages shell configuration, git settings, and Neovim setup.


		Personal dotfiles for macOS development environment. Manages shell, git, Neovim, tmux, and terminal configuration.

		## Table of Contents


		### General

		- [Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle) — Add a `Brewfile` to version-control all Homebrew dependencies (fzf, ripgrep, direnv, neovim, etc.) so the full environment can be reproduced with `brew bundle`.

Conversation

samuelreh commented Feb 25, 2026

Summary

Test plan

Uh oh!

samuelreh commented Feb 26, 2026

Uh oh!

samuelreh commented Feb 26, 2026

Uh oh!

samuelreh commented Feb 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 27, 2026

Uh oh!

samuelreh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 27, 2026

Uh oh!

samuelreh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 27, 2026

Uh oh!

samuelreh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

samuelreh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iris-test-samr Bot commented Feb 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant