ldraney/tmux-custom
1
0
Fork 0
Code Issues 3 Pull requests 3 Projects Releases Packages Wiki Activity Actions

Add plugins and config docs, rewrite README as TOC #8

Merged
ldraney merged 2 commits from docs/plugins-and-readme into main 2026-06-12 04:45:44 +00:00
Conversation 2 Commits 2 Files changed 3 +150 -9
ldraney commented 2026-06-12 04:42:02 +00:00
Owner
Copy link

Summary

  • Adds docs/plugins.md documenting all 7 TPM plugins with keybindings and config overrides
  • Adds docs/config-reference.md with annotated walk-through of .tmux.conf
  • Rewrites README.md as a table of contents linking to docs/

Changes

  • docs/plugins.md: new -- plugin docs with keybindings, overrides section
  • docs/config-reference.md: new -- annotated config walk-through
  • README.md: rewritten from bare feature list to setup + docs TOC + feature summary

Test Plan

  • Markdown renders correctly on Forgejo
  • Plugin list matches .tmux.conf plugin declarations
  • Config reference matches current .tmux.conf on main
  • README doc links resolve correctly

Review Checklist

  • Passed automated review-fix loop
  • No secrets committed
  • No unnecessary file changes
  • Commit messages are descriptive
  • Feature flag needed? No -- documentation only

Related Notes

  • ldraney/tmux-custom #7 -- the Forgejo issue this PR implements
  • Closes #7
## Summary - Adds `docs/plugins.md` documenting all 7 TPM plugins with keybindings and config overrides - Adds `docs/config-reference.md` with annotated walk-through of .tmux.conf - Rewrites `README.md` as a table of contents linking to docs/ ## Changes - `docs/plugins.md`: new -- plugin docs with keybindings, overrides section - `docs/config-reference.md`: new -- annotated config walk-through - `README.md`: rewritten from bare feature list to setup + docs TOC + feature summary ## Test Plan - [ ] Markdown renders correctly on Forgejo - [ ] Plugin list matches .tmux.conf plugin declarations - [ ] Config reference matches current .tmux.conf on main - [ ] README doc links resolve correctly ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive - [ ] Feature flag needed? No -- documentation only ## Related Notes - `ldraney/tmux-custom #7` -- the Forgejo issue this PR implements - Closes #7 
Documents all active TPM plugins with keybindings and config overrides.
Adds annotated config reference. README now serves as entry point
linking to docs/ for details.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ldraney commented 2026-06-12 04:43:34 +00:00
Author
Owner
Copy link

PR #8 Review

DOMAIN REVIEW

Documentation-only PR adding docs/plugins.md, docs/config-reference.md, and rewriting README.md as a table of contents. Reviewed against the actual .tmux.conf on main as the source of truth.

Plugin list accuracy (docs/plugins.md vs .tmux.conf lines 77-83):
All 7 @plugin declarations are documented: tpm, tmux-sensible, tmux-resurrect, tmux-continuum, tmux-pain-control, tmux-prefix-highlight, catppuccin/tmux. Count and names match exactly.

Config overrides accuracy (docs/plugins.md "Config Overrides" vs .tmux.conf lines 98-108):
All three post-TPM overrides are documented correctly:

  • automatic-rename off (line 98)
  • swap-window without -d for bubble-sort behavior (lines 103-104)
  • window-status-format override from #T to #W (lines 107-108)

The explanations for WHY each override exists are accurate and helpful.

README doc links:

  • docs/session-management.md -- exists on main, resolves correctly
  • docs/plugins.md -- added in this PR, resolves correctly
  • docs/config-reference.md -- added in this PR, resolves correctly

BLOCKERS

1. Wayland/wl-copy claim is factually wrong

docs/config-reference.md includes this clipboard table:

| Wayland | `wl-copy` |

And README.md says:

Vi mode copy with OS-aware clipboard (macOS/Wayland/X11/WSL2)

Neither wl-copy nor any Wayland-specific code exists in .tmux.conf. The actual Linux branch (lines 44-60) uses xclip -sel clip || clip.exe -- there is no Wayland detection or wl-copy fallback. Commit 6ce727b ("Add Wayland clipboard support (wl-copy)") appears in history but the code was removed/reverted before reaching main.

Fix: Remove the Wayland row from the clipboard table in config-reference.md and remove "Wayland/" from the README features list. The table should only list macOS/pbcopy and X11-WSL2/xclip-clip.exe. If Wayland support is desired, it needs to be implemented in .tmux.conf first, then documented.

This is a BLOCKER because documentation claiming a feature that does not exist will confuse users and fail the PR's own test plan item: "Config reference matches current .tmux.conf on main."

NITS

  1. config-reference.md line 65-66 -- Files table references .tmux-battery.conf as "Legacy battery config (macOS-only, from earlier setup)." This is accurate but consider whether documenting a legacy file in a fresh config reference creates confusion. A one-line note saying "unused; battery is now inline in .tmux.conf" would clarify status.

  2. README.md removed the .tmux-battery.conf symlink from the Setup section. This is correct since battery config is inline now, but there is no migration note for existing users who may have the old symlink. Minor since this is a personal config repo.

  3. docs/plugins.md pain-control keybinding table -- the prefix + \| line uses a backslash-pipe that may render oddly depending on the markdown renderer. Verify it renders correctly on Forgejo.

SOP COMPLIANCE

  • PR body has Summary, Changes, Test Plan, Related sections
  • No secrets committed
  • No unnecessary file changes (3 files, all documentation, all on-topic)
  • Commit messages are descriptive (based on branch name docs/plugins-and-readme)
  • Test plan item "Plugin list matches .tmux.conf" -- PASSES on review
  • Test plan item "Config reference matches current .tmux.conf" -- FAILS (Wayland claim)
  • Test plan item "README doc links resolve" -- PASSES on review

PROCESS OBSERVATIONS

Clean PR structure. The test plan is well-designed -- it caught the Wayland discrepancy when applied. The documentation quality is high: plugin descriptions explain not just what each plugin does but why it matters, and the config overrides section explains the reasoning behind each override. Once the Wayland inaccuracy is fixed, this is ready to ship.

VERDICT: NOT APPROVED

One BLOCKER: Wayland/wl-copy documented as a feature but does not exist in the actual config. Fix the factual inaccuracy in both docs/config-reference.md and README.md, then re-review.

## PR #8 Review ### DOMAIN REVIEW Documentation-only PR adding `docs/plugins.md`, `docs/config-reference.md`, and rewriting `README.md` as a table of contents. Reviewed against the actual `.tmux.conf` on main as the source of truth. **Plugin list accuracy (docs/plugins.md vs .tmux.conf lines 77-83):** All 7 `@plugin` declarations are documented: tpm, tmux-sensible, tmux-resurrect, tmux-continuum, tmux-pain-control, tmux-prefix-highlight, catppuccin/tmux. Count and names match exactly. **Config overrides accuracy (docs/plugins.md "Config Overrides" vs .tmux.conf lines 98-108):** All three post-TPM overrides are documented correctly: - `automatic-rename off` (line 98) - `swap-window` without `-d` for bubble-sort behavior (lines 103-104) - `window-status-format` override from `#T` to `#W` (lines 107-108) The explanations for WHY each override exists are accurate and helpful. **README doc links:** - `docs/session-management.md` -- exists on main, resolves correctly - `docs/plugins.md` -- added in this PR, resolves correctly - `docs/config-reference.md` -- added in this PR, resolves correctly ### BLOCKERS **1. Wayland/wl-copy claim is factually wrong** `docs/config-reference.md` includes this clipboard table: ``` | Wayland | `wl-copy` | ``` And `README.md` says: > Vi mode copy with OS-aware clipboard (macOS/Wayland/X11/WSL2) **Neither `wl-copy` nor any Wayland-specific code exists in `.tmux.conf`.** The actual Linux branch (lines 44-60) uses `xclip -sel clip || clip.exe` -- there is no Wayland detection or `wl-copy` fallback. Commit `6ce727b` ("Add Wayland clipboard support (wl-copy)") appears in history but the code was removed/reverted before reaching main. **Fix:** Remove the Wayland row from the clipboard table in `config-reference.md` and remove "Wayland/" from the README features list. The table should only list macOS/pbcopy and X11-WSL2/xclip-clip.exe. If Wayland support is desired, it needs to be implemented in `.tmux.conf` first, then documented. This is a BLOCKER because documentation claiming a feature that does not exist will confuse users and fail the PR's own test plan item: "Config reference matches current .tmux.conf on main." ### NITS 1. **config-reference.md line 65-66 -- Files table references `.tmux-battery.conf`** as "Legacy battery config (macOS-only, from earlier setup)." This is accurate but consider whether documenting a legacy file in a fresh config reference creates confusion. A one-line note saying "unused; battery is now inline in `.tmux.conf`" would clarify status. 2. **README.md removed the `.tmux-battery.conf` symlink** from the Setup section. This is correct since battery config is inline now, but there is no migration note for existing users who may have the old symlink. Minor since this is a personal config repo. 3. **docs/plugins.md pain-control keybinding table** -- the `prefix + \|` line uses a backslash-pipe that may render oddly depending on the markdown renderer. Verify it renders correctly on Forgejo. ### SOP COMPLIANCE - [x] PR body has Summary, Changes, Test Plan, Related sections - [x] No secrets committed - [x] No unnecessary file changes (3 files, all documentation, all on-topic) - [x] Commit messages are descriptive (based on branch name `docs/plugins-and-readme`) - [ ] Test plan item "Plugin list matches .tmux.conf" -- PASSES on review - [ ] Test plan item "Config reference matches current .tmux.conf" -- FAILS (Wayland claim) - [ ] Test plan item "README doc links resolve" -- PASSES on review ### PROCESS OBSERVATIONS Clean PR structure. The test plan is well-designed -- it caught the Wayland discrepancy when applied. The documentation quality is high: plugin descriptions explain not just what each plugin does but why it matters, and the config overrides section explains the reasoning behind each override. Once the Wayland inaccuracy is fixed, this is ready to ship. ### VERDICT: NOT APPROVED One BLOCKER: Wayland/wl-copy documented as a feature but does not exist in the actual config. Fix the factual inaccuracy in both `docs/config-reference.md` and `README.md`, then re-review.
Removed wl-copy from clipboard table and README feature list.
That code lives on kitty-tmux-optimization branch, not main.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
ldraney commented 2026-06-12 04:45:27 +00:00
Author
Owner
Copy link

PR #8 Review (Re-review)

DOMAIN REVIEW

Documentation-only PR (Markdown). Tech stack: tmux config + Markdown docs. Domain checks applied: documentation accuracy against the actual .tmux.conf on main.

Previous blocker resolved: The Wayland/wl-copy references that were flagged in the prior review are gone. docs/config-reference.md now correctly lists xclip / clip.exe for X11/WSL2, matching the actual clipboard commands in .tmux.conf (lines 44-60). No Wayland or wl-copy text appears anywhere in the diff.

Cross-check: docs vs .tmux.conf -- all verified accurate:

  • Core settings (mouse, status-position, status-interval, renumber-windows) -- match
  • Session/window navigation (MouseDown1StatusLeft, MouseDrag1Status) -- match
  • Pane behavior (split with pane_current_path, even-horizontal hooks) -- match
  • Vi mode clipboard table (pbcopy on macOS, xclip/clip.exe on X11/WSL2) -- match
  • Status bar (prefix_highlight + battery with OS detection) -- match
  • All 7 plugins documented match the 7 @plugin declarations in .tmux.conf
  • Config overrides (automatic-rename off, swap-window without -d, window-status-format with #W) -- all match post-TPM settings
  • README feature list accurately reflects what the config actually does
  • All three doc links in README resolve to existing files (docs/session-management.md, docs/plugins.md, docs/config-reference.md)
  • .tmux-battery.conf referenced in the Files table exists in the repo

BLOCKERS

None.

NITS

  1. docs/config-reference.md Files table describes .tmux-battery.conf as "Legacy battery config (macOS-only, from earlier setup)" but the main .tmux.conf does not source or reference this file. Consider noting explicitly that it is unused/orphaned, or removing it in a follow-up.

  2. docs/config-reference.md line ending: the file ends without a trailing newline. Minor, but most linters expect one.

SOP COMPLIANCE

  • PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related)
  • No secrets committed
  • No unnecessary file changes (3 files, all documentation, all scoped to issue #7)
  • Commit messages -- single commit, descriptive title
  • Closes #7 referenced in PR body

PROCESS OBSERVATIONS

Clean documentation PR. Low change-failure risk (no code changes). The test plan checkboxes are appropriate for a docs-only PR. All prior review findings have been addressed.

VERDICT: APPROVED

## PR #8 Review (Re-review) ### DOMAIN REVIEW Documentation-only PR (Markdown). Tech stack: tmux config + Markdown docs. Domain checks applied: documentation accuracy against the actual `.tmux.conf` on main. **Previous blocker resolved:** The Wayland/wl-copy references that were flagged in the prior review are gone. `docs/config-reference.md` now correctly lists `xclip` / `clip.exe` for X11/WSL2, matching the actual clipboard commands in `.tmux.conf` (lines 44-60). No Wayland or `wl-copy` text appears anywhere in the diff. **Cross-check: docs vs .tmux.conf** -- all verified accurate: - Core settings (mouse, status-position, status-interval, renumber-windows) -- match - Session/window navigation (MouseDown1StatusLeft, MouseDrag1Status) -- match - Pane behavior (split with pane_current_path, even-horizontal hooks) -- match - Vi mode clipboard table (pbcopy on macOS, xclip/clip.exe on X11/WSL2) -- match - Status bar (prefix_highlight + battery with OS detection) -- match - All 7 plugins documented match the 7 `@plugin` declarations in .tmux.conf - Config overrides (automatic-rename off, swap-window without -d, window-status-format with #W) -- all match post-TPM settings - README feature list accurately reflects what the config actually does - All three doc links in README resolve to existing files (`docs/session-management.md`, `docs/plugins.md`, `docs/config-reference.md`) - `.tmux-battery.conf` referenced in the Files table exists in the repo ### BLOCKERS None. ### NITS 1. `docs/config-reference.md` Files table describes `.tmux-battery.conf` as "Legacy battery config (macOS-only, from earlier setup)" but the main `.tmux.conf` does not source or reference this file. Consider noting explicitly that it is unused/orphaned, or removing it in a follow-up. 2. `docs/config-reference.md` line ending: the file ends without a trailing newline. Minor, but most linters expect one. ### SOP COMPLIANCE - [x] PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related) - [x] No secrets committed - [x] No unnecessary file changes (3 files, all documentation, all scoped to issue #7) - [x] Commit messages -- single commit, descriptive title - [x] Closes #7 referenced in PR body ### PROCESS OBSERVATIONS Clean documentation PR. Low change-failure risk (no code changes). The test plan checkboxes are appropriate for a docs-only PR. All prior review findings have been addressed. ### VERDICT: APPROVED
ldraney deleted branch docs/plugins-and-readme 2026-06-12 04:45:44 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/tmux-custom!8
No description provided.