Refactor configuration rules for dotfiles, Git/SSH, GitHub workflows, shell, and terminal settings to improve clarity and consistency. Update conventions for managing shared and host-specific configurations, enhance formatting guidelines, and ensure compliance with pre-commit standards.

Author: FridrichMethod

.claude/README.md

@@ -0,0 +1,8 @@
+# Claude Topic Docs
+
+Claude Code uses shared docs referenced by `CLAUDE.md`:
+
+- `.cursor/shared/shell.md`
+- `.cursor/shared/git-ssh.md`
+- `.cursor/shared/stow-scripts.md`
+- `.cursor/shared/workflows.md`

.codex/README.md

@@ -0,0 +1,8 @@
+# Codex Topic Docs
+
+Codex uses shared docs referenced by `AGENTS.md`:
+
+- `.cursor/shared/shell.md`
+- `.cursor/shared/git-ssh.md`
+- `.cursor/shared/stow-scripts.md`
+- `.cursor/shared/workflows.md`

.cursor/rules/core-dotfiles.mdc

@@ -5,8 +5,9 @@ alwaysApply: true
 
 # Dotfiles conventions
 
-- This repo is managed with GNU Stow; keep packages as top-level folders.
-- Mirror `$HOME` paths inside packages (e.g., `.config/...`, `.ssh/...`).
-- Put shared defaults in `common/`; host-specific overrides live in host folders.
-- Avoid absolute paths and secrets in committed configs.
-- Update `stow-all.sh` and README when adding packages or changing usage.
+- Manage links with GNU Stow; package directories must mirror `$HOME` paths (for example `.config/...`, `.ssh/...`).
+- Keep shared defaults in `common/`; host overlays belong in `mac/`, `sherlock/`, `wsl-ubuntu/`, `lab-ubuntu/`, `marlowe/`, `fedora/`, `ubuntu/`, or `win/`.
+- Follow the layering model: stow `common/` first, then one host folder via `./stow-all.sh [host]`.
+- Keep `.stowrc`, `stow-all.sh`, and `README.md` consistent whenever package layout or setup commands change.
+- Base configs in `common/` should source host extension files from `~/.config/...` when per-host behavior is needed.
+- Never commit secrets, private keys, or machine-specific absolute paths.

.cursor/rules/git-ssh-configs.mdc

@@ -3,6 +3,7 @@ description: Git and SSH config conventions
 globs:
   - "**/.gitconfig"
   - "**/.gitconfig_local"
+  - "**/.gitignore_global"
   - "**/.gitignore"
   - "**/.gitmodules"
   - "**/.ssh/config"
@@ -12,7 +13,9 @@ alwaysApply: false
 
 # Git and SSH configs
 
-- Keep shared git settings in `common/git/.gitconfig`; put machine-specific overrides in `*/git/.gitconfig_local`.
-- Prefer include/includeIf blocks over duplicating settings across hosts.
-- Do not commit secrets; SSH config should reference key paths only.
-- Keep `.gitmodules` in sync with submodule paths and URLs.
+- Keep shared Git defaults in `common/git/.gitconfig`; host-local identity or machine overrides live in `*/git/.gitconfig_local`.
+- Preserve the include pattern used by this repo: `[include] path = ~/.gitconfig_local` in shared config.
+- Keep SSH root config minimal: `common/ssh/.ssh/config` should delegate to `Include ~/.ssh/config.d/*.conf`.
+- Split host/service SSH rules into focused files under `.ssh/config.d/` (for example `github.conf`, `stanford.conf`, `legacy.conf`).
+- Never commit private key material, tokens, or secrets in Git/SSH config files.
+- Keep `.gitmodules` synchronized with submodule path and URL changes.

.cursor/rules/github-workflows.mdc

@@ -1,11 +1,15 @@
 ---
 description: GitHub workflow conventions
-globs: ".github/workflows/*.yml"
+globs:
+  - ".github/workflows/*.yml"
+  - ".pre-commit-config.yaml"
 alwaysApply: false
 ---
 
 # GitHub workflows
 
-- Keep workflows minimal and deterministic; pin action versions.
-- Use repo tooling (`shellcheck`, `shfmt`, `stylua`) when adding workflow steps that run scripts.
-- Update README when CI behavior or required checks change.
+- Keep workflows deterministic and pinned; avoid floating action tags.
+- Keep CI behavior aligned with `.pre-commit-config.yaml` tooling (`shellcheck`, `shfmt`, `stylua`, and hygiene hooks).
+- Update `.github/workflows/ci.yml` when repo lint/format policy changes.
+- Keep `.github/workflows/update-pymolscripts-submodule.yml` focused on submodule sync logic only.
+- If workflow behavior changes user setup or contribution flow, update `README.md` in the same change.

.cursor/rules/shell-configs.mdc

@@ -1,18 +1,23 @@
 ---
 description: Shell config and script conventions
 globs:
+  - "**/.aliases"
   - "**/.zsh*"
   - "**/.bash*"
   - "**/.profile"
+  - "**/.config/sh/**"
+  - "**/.config/bash/**"
+  - "**/.config/zsh/**"
   - "**/*.sh"
   - "**/*.zsh"
 alwaysApply: false
 ---
 
 # Shell configs
 
-- Keep POSIX sh compatible logic in `sh/` packages; use bash/zsh features only in their files.
-- Prefer aliases in `.zsh_aliases` / `.bash_aliases`; keep `*.rc` focused on options and sourcing.
-- Place host-specific logic in host folders, guarded by OS/host checks if needed.
-- For scripts in `common/zsh/.local/bin`, include a shebang and keep output quiet by default.
-- Keep formatting compatible with `shfmt` and avoid shellcheck violations.
+- Keep POSIX-compatible logic in `common/sh/` and `*/sh/`; use Bash/Zsh-only features only in their shell-specific files.
+- Preserve the override chain: shared `common/sh/.aliases` and `common/sh/.profile` source host files from `~/.config/sh/` when present.
+- Keep `*.rc` files focused on options and sourcing; prefer aliases/functions in `.bash_aliases`, `.zsh_aliases`, and `~/.config/sh/.aliases`.
+- Keep dotfiles update integration consistent: shell startup files may source `dotfiles-update.sh`, but the script itself remains POSIX `sh`.
+- Match pre-commit formatting: `shfmt -i 4 -ci` with dialect-specific `-ln bash`, `-ln posix`, or `-ln zsh`.
+- Avoid shellcheck violations; if a suppression is required, scope it to a single line with a brief reason.

.cursor/rules/stow-scripts.mdc

@@ -0,0 +1,17 @@
+---
+description: Stow helper and update script conventions
+globs:
+  - "stow-all.sh"
+  - "dotfiles-update.sh"
+  - ".stowrc"
+alwaysApply: false
+---
+
+# Stow and update scripts
+
+- Keep `stow-all.sh` as the canonical entrypoint: stow `common/` first, then optional host packages.
+- Preserve `stow --restow --no-folding` behavior unless there is a repo-wide migration plan.
+- Keep `.stowrc` as the source of global Stow target/ignore defaults (`--target=~` and ignore patterns).
+- Use `set -euo pipefail` in Bash scripts like `stow-all.sh`; keep POSIX `sh` scripts (`dotfiles-update.sh`) portable.
+- For startup-update logic, keep the `_DOTFILES_CHECKED` session-marker pattern so checks run once per login session.
+- If setup flow changes, update both script comments and `README.md` usage examples together.

.cursor/rules/terminal-configs.mdc

@@ -9,6 +9,8 @@ alwaysApply: false
 
 # Terminal configs
 
-- Keep shared settings in `common/`; host-specific overrides belong in host folders.
-- Group related options and keep key mappings together for readability.
-- For wezterm Lua, use explicit tables and avoid side effects at load time.
+- Keep shared terminal defaults in `common/`; host-specific overrides belong in host folders only.
+- Group related settings (font, appearance, keymaps, shell integration) in contiguous blocks.
+- For `common/kitty/.config/kitty/current-theme.conf`, keep it theme-only (no unrelated behavior settings).
+- For `.wezterm.lua`, prefer explicit tables and pure setup logic (no stateful side effects at import time).
+- Keep comments short and task-oriented; remove stale commented-out settings.

.cursor/shared/git-ssh.md

@@ -0,0 +1,9 @@
+# Git and SSH conventions
+
+- Keep shared Git config in `common/git/.gitconfig`.
+- Keep host-local Git overrides in `*/git/.gitconfig_local`.
+- Preserve include chain: `[include] path = ~/.gitconfig_local`.
+- Keep SSH root config minimal in `common/ssh/.ssh/config`:
+  - `Include ~/.ssh/config.d/*.conf`
+- Keep SSH targets split by concern in `.ssh/config.d/*.conf`.
+- Do not commit secrets or private key material.

.cursor/shared/shell.md

@@ -0,0 +1,12 @@
+# Shell conventions
+
+- Keep POSIX logic in `common/sh/` and host `*/sh/` paths.
+- Use Bash/Zsh-specific syntax only in matching shell files.
+- Preserve override sourcing patterns from shared files:
+  - `common/sh/.aliases` sources `~/.config/sh/.aliases`
+  - `common/sh/.profile` sources `~/.config/sh/.profile`
+- Keep startup flow quiet and idempotent; avoid duplicate side effects.
+- Follow pre-commit shell style:
+  - Bash: `shfmt -i 4 -ci -ln bash`
+  - POSIX: `shfmt -i 4 -ci -ln posix`
+  - Zsh: `shfmt -i 4 -ci -ln zsh`