[codex] organize dotfiles repository layout

.github/workflows/test.yml

@@ -77,12 +77,12 @@ jobs:
       - name: Validate shell configurations
         run: |
           # Test zsh configuration syntax
-          zsh -n zshrc || echo "Warning: zshrc has syntax issues"
+          zsh -n home/zshrc || echo "Warning: zshrc has syntax issues"
 
           # Test bash configuration syntax  
-          bash -n bash_profile || echo "Warning: bash_profile has syntax issues"
+          bash -n home/bash_profile || echo "Warning: bash_profile has syntax issues"
 
       - name: Validate git configuration
         run: |
           # Test git configuration
-          git config --file gitconfig --list > /dev/null
+          git config --file home/gitconfig --list > /dev/null

.gitignore

@@ -32,7 +32,7 @@ logs/
 # Vim/Neovim
 .viminfo
 .vim/view/*
-nvim/lazy-lock.json
+config/nvim/lazy-lock.json
 
 # Local generated editor state
 .omx/
@@ -62,4 +62,4 @@ private/
 local/
 
 # Tmux Plugin Manager installs plugin checkouts here; do not track nested repos.
-tmux/plugins/
+config/tmux/plugins/

AGENTS.md

@@ -1,7 +1,7 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-This repository manages environment configuration through symlinks. Core shell and Git files at the repo root are linked into `~/.*`, and config directories such as `nvim/` and `ghostty/` are linked into `~/.config/`. Use `scripts/install-enhanced.sh` through the Makefile for validation, backup, and verbose installs. Editor config now lives entirely in `nvim/` for a Neovim-only setup. Automation scripts are in `scripts/`, tests in `tests/`, and Git hooks under `git/templates/hooks/`.
+This repository manages environment configuration through symlinks. Home-level dotfiles and shell modules live under `home/`; selected files are linked into `~/.*`. Config directories such as `config/nvim/` and `config/ghostty/` are linked into `~/.config/`. Use `scripts/install-enhanced.sh` through the Makefile for validation, backup, and verbose installs. Editor config now lives entirely in `config/nvim/` for a Neovim-only setup. Automation scripts are in `scripts/`, tests in `tests/`, extended docs in `docs/`, and Git hooks under `home/git/templates/hooks/`.
 
 ## Build, Test, and Development Commands
 Main workflows:
@@ -18,13 +18,13 @@ Main workflows:
 - `brew bundle --file=Brewfile`: installs the Homebrew-managed toolchain.
 
 ## Coding Style & Naming Conventions
-Match the style of the file you edit instead of normalizing the repo. Shell scripts use Bash with `set -euo pipefail`, descriptive helper functions, and four-space indentation; Makefile recipes must stay tab-indented. Lua in `nvim/lua/` uses compact two-space indentation. Prefer kebab-case for scripts such as `install-enhanced.sh`, and keep test files in the `test_*.bats` pattern. Run `make lint` before submitting shell changes.
+Match the style of the file you edit instead of normalizing the repo. Shell scripts use Bash with `set -euo pipefail`, descriptive helper functions, and four-space indentation; Makefile recipes must stay tab-indented. Lua in `config/nvim/lua/` uses compact two-space indentation. Prefer kebab-case for scripts such as `install-enhanced.sh`, and keep test files in the `test_*.bats` pattern. Run `make lint` before submitting shell changes.
 
 ## Testing Guidelines
-Primary coverage is in `tests/test_dotfiles.bats`, which checks script syntax, install validation, Git config parsing, and Neovim migration expectations. Add or update Bats tests whenever install behavior or validation logic changes. Before opening a PR, run `make check`; for focused work, use `bats tests/test_dotfiles.bats`, `git config --file gitconfig --list`, and `zsh -n zshrc`.
+Primary coverage is in `tests/test_dotfiles.bats`, which checks script syntax, install validation, Git config parsing, and Neovim migration expectations. Add or update Bats tests whenever install behavior or validation logic changes. Before opening a PR, run `make check`; for focused work, use `bats tests/test_dotfiles.bats`, `git config --file home/gitconfig --list`, `zsh -n home/zshrc`, and `zsh -n home/zsh/*.zsh`.
 
 ## Commit & Pull Request Guidelines
 Recent history favors short, imperative commit subjects, with a scope prefix such as `docs:` when useful. Keep messages specific, for example: `docs: update install instructions` or `Force nvim to be the EDITOR.` PRs should explain the config change, list validation commands run, and note follow-up such as `brew bundle` or opening Neovim to install plugins. Include screenshots only for UI changes or documentation imagery.
 
 ## Security & Configuration Tips
-Do not commit machine-specific secrets, tokens, or private paths unless they are already intentional repo conventions. Prefer environment variables for sensitive values and run `make security` after touching shell startup files, install scripts, or Git hooks. Installs create `~/.logs`, back up files under `~/.dotfiles-backup-*`, and link config directories such as `nvim/` and `ghostty/` into `~/.config/`.
+Do not commit machine-specific secrets, tokens, or private paths unless they are already intentional repo conventions. Prefer environment variables for sensitive values and run `make security` after touching shell startup files, install scripts, or Git hooks. Installs create `~/.logs`, back up files under `~/.dotfiles-backup-*`, and link config directories such as `config/nvim/` and `config/ghostty/` into `~/.config/`.

Brewfile

@@ -76,8 +76,8 @@ brew "nmap"
 brew "no-more-secrets"
 brew "nodenv"
 brew "nvm"
-brew "ollama"
 brew "oh-my-posh"
+brew "ollama"
 brew "ripgrep"
 brew "opencode"
 brew "php"
@@ -105,6 +105,7 @@ brew "solargraph"
 brew "speedtest-cli"
 brew "sqlc"
 brew "sslscan"
+brew "subversion"
 brew "summarize"
 brew "swagger-codegen"
 brew "telnet"

Makefile

@@ -5,7 +5,7 @@ SHELL := /bin/bash
 INSTALL_SCRIPT := scripts/install-enhanced.sh
 TEST_SCRIPT := scripts/test-install.sh
 SECURITY_SCRIPT := scripts/security-check.sh
-TMUX_OPEN_URL_SCRIPT := tmux/open-url.sh
+TMUX_OPEN_URL_SCRIPT := config/tmux/open-url.sh
 SHELL_SCRIPTS := $(INSTALL_SCRIPT) $(TEST_SCRIPT) $(SECURITY_SCRIPT) $(TMUX_OPEN_URL_SCRIPT)
 BATS_TESTS := tests/test_dotfiles.bats
 

README.md

@@ -55,17 +55,22 @@ dotfiles/
 ├── .github/workflows/    # CI/CD automation
 ├── scripts/             # Installation, test, and validation scripts
 ├── tests/              # Automated tests
-├── aliases             # Shell aliases
-├── bash_profile        # Bash configuration
-├── exports             # Environment variables
-├── functions           # Shell functions
-├── git/                # Git templates and hooks
-├── gitconfig           # Git configuration
-├── nvim/               # Neovim configuration
-├── ohmyposh/           # Oh My Posh prompt themes
-├── tmux/               # Tmux configuration
-├── zsh/                # Modular Zsh configuration
-├── zshrc               # Zsh module loader
+├── home/               # Files symlinked into ~/.* plus shell support
+│   ├── aliases         # Shell aliases
+│   ├── bash_profile    # Bash configuration
+│   ├── exports         # Environment variables
+│   ├── functions       # Shell functions
+│   ├── git/            # Git templates and hooks
+│   ├── gitconfig       # Git configuration
+│   ├── screenrc        # GNU Screen configuration
+│   ├── zsh/            # Modular Zsh configuration
+│   └── zshrc           # Zsh module loader
+├── config/             # Directories symlinked into ~/.config/*
+│   ├── ghostty/        # Ghostty terminal configuration
+│   ├── nvim/           # Neovim configuration
+│   ├── ohmyposh/       # Oh My Posh prompt themes
+│   └── tmux/           # Tmux configuration
+├── docs/               # Extended project documentation
 ├── Brewfile            # Package management
 └── Makefile            # Build automation
 ```
@@ -105,18 +110,18 @@ make check            # Complete quality validation
 ./scripts/test-install.sh
 
 # Validate configurations
-git config --file gitconfig --list
-zsh -n zshrc
-zsh -n zsh/*.zsh
+git config --file home/gitconfig --list
+zsh -n home/zshrc
+zsh -n home/zsh/*.zsh
 ```
 
 ## 📦 Requirements
 
 ### Essential
 - **Git**: Version control
 - **Zsh**: Modern shell
-- **zinit**: Zsh plugin manager (bootstrapped automatically by `zsh/00-zinit.zsh`)
-- **Oh My Posh**: Prompt engine using configs from `ohmyposh/`
+- **zinit**: Zsh plugin manager (bootstrapped automatically by `home/zsh/00-zinit.zsh`)
+- **Oh My Posh**: Prompt engine using configs from `config/ohmyposh/`
 - **Homebrew**: Package management (macOS)
 
 ### Optional
@@ -141,18 +146,18 @@ brew bundle --file=Brewfile
 ## 🔄 Neovim-only editor setup
 
 This repository now uses **Neovim as the only tracked editor configuration**.
-The active runtime lives under `nvim/`, with:
+The active runtime lives under `config/nvim/`, with:
 
-- `nvim/init.vim` as the thin entrypoint
-- `nvim/lua/config/*` for general editor behavior
-- `nvim/lua/plugins/*` for grouped lazy.nvim plugin specs
-- `nvim/coc-settings.json` for CoC settings
+- `config/nvim/init.vim` as the thin entrypoint
+- `config/nvim/lua/config/*` for general editor behavior
+- `config/nvim/lua/plugins/*` for grouped lazy.nvim plugin specs
+- `config/nvim/coc-settings.json` for CoC settings
 
 Supporting Neovim docs:
 
-- `nvim/README.md` — structure and ownership
-- `nvim/PLUGIN_AUDIT.md` — current plugin inventory
-- `nvim/PLUGIN_REEVALUATION.md` — keep/remove/replace decisions
+- `docs/nvim/README.md` — structure and ownership
+- `docs/nvim/PLUGIN_AUDIT.md` — current plugin inventory
+- `docs/nvim/PLUGIN_REEVALUATION.md` — keep/remove/replace decisions
 
 ### Setup Neovim Plugins
 ```bash
@@ -167,7 +172,7 @@ nvim -c "Lazy install" -c "qa"
 ## 🧩 Tmux plugin setup
 
 The installer bootstraps [TPM](https://github.com/tmux-plugins/tpm) into
-`~/.config/tmux/plugins/tpm`. Other tmux plugins are declared in `tmux/tmux.conf`
+`~/.config/tmux/plugins/tpm`. Other tmux plugins are declared in `config/tmux/tmux.conf`
 and installed by TPM.
 
 ```bash
@@ -182,7 +187,7 @@ tmux source-file ~/.config/tmux/tmux.conf
 - Asynchronous processing
 - Modern architecture
 - Lua configuration support
-- No split ownership between `nvim/` and legacy Vim files
+- No split ownership between `config/nvim/` and legacy Vim files
 
 ## 🏗️ CI/CD & Automation
 
@@ -212,7 +217,7 @@ fi
 ```
 
 ### Adding New Configurations
-1. Add the file to the repository
+1. Add home-level dotfiles under `home/`, or XDG config directories under `config/`
 2. Update `HOME_FILES` or `CONFIG_FILES` in `scripts/install-enhanced.sh`
 3. Test with `make test`
 4. Document any dependencies
@@ -287,7 +292,7 @@ make install
 exec zsh
 ```
 
-The zinit bootstrap in `zsh/00-zinit.zsh` installs zinit into
+The zinit bootstrap in `home/zsh/00-zinit.zsh` installs zinit into
 `${XDG_DATA_HOME:-$HOME/.local/share}/zinit/zinit.git` on first shell startup.
 
 ### Getting Help
@@ -337,4 +342,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-For the current improvement backlog, see [DEVOPS_RECOMMENDATIONS.md](DEVOPS_RECOMMENDATIONS.md).
+For the current improvement backlog, see [docs/DEVOPS_RECOMMENDATIONS.md](docs/DEVOPS_RECOMMENDATIONS.md).

DEVOPS_RECOMMENDATIONS.md → docs/DEVOPS_RECOMMENDATIONS.md

@@ -9,11 +9,11 @@ and Ubuntu. The remaining work should stay incremental and test-backed.
 - `make check` runs lint, security checks, installation tests, and Bats tests.
 - `scripts/install-enhanced.sh` validates, backs up, links home files, links
   config directories, and bootstraps TPM when enabled.
-- `zshrc` is a thin loader for `zsh/*.zsh` modules.
+- `home/zshrc` is a thin loader for `home/zsh/*.zsh` modules.
 - Zsh plugins are managed by zinit; the prompt is managed by Oh My Posh from
-  `ohmyposh/`.
+  `config/ohmyposh/`.
 - Neovim is the only tracked editor runtime and uses lazy.nvim modules.
-- Tmux and Ghostty configs are tracked under `~/.config/` symlink targets.
+- Tmux and Ghostty config sources live under `config/` and are linked to `~/.config/` targets.
 
 ## Recommended Next Improvements
 
@@ -49,7 +49,7 @@ package.
 failures can otherwise be hard to diagnose.
 
 **Plan:**
-1. Add a lightweight `zsh/README.md` documenting module order and ownership.
+1. Add a lightweight `docs/zsh.md` documenting module order and ownership.
 2. Add a `make doctor-shell` target or script that checks zinit, Oh My Posh,
    fzf, zoxide, and linked config paths.
 3. Keep shell startup quiet; put diagnostics in explicit doctor commands.

IMPLEMENTATION_SUMMARY.md → docs/IMPLEMENTATION_SUMMARY.md

@@ -9,24 +9,24 @@ contracts.
 
 ## Shell
 
-- `zshrc` is a thin entrypoint that loads `zsh/*.zsh` in lexical order.
-- `zsh/00-zinit.zsh` bootstraps zinit, loads Zsh plugins/snippets, and initializes
+- `home/zshrc` is a thin entrypoint that loads `home/zsh/*.zsh` in lexical order.
+- `home/zsh/00-zinit.zsh` bootstraps zinit, loads Zsh plugins/snippets, and initializes
   Oh My Posh when available.
-- `ohmyposh/` contains tracked prompt themes linked to `~/.config/ohmyposh`.
-- Shared aliases, exports, and functions are sourced from `zsh/10-shared-shell.zsh`.
+- `config/ohmyposh/` contains tracked prompt themes linked to `~/.config/ohmyposh`.
+- Shared aliases, exports, and functions are sourced from `home/zsh/10-shared-shell.zsh`.
 
 ## Editor
 
 - Neovim is the only tracked editor configuration.
-- `nvim/init.vim` delegates behavior to Lua modules under `nvim/lua/config` and
-  plugin specs under `nvim/lua/plugins`.
+- `config/nvim/init.vim` delegates behavior to Lua modules under `config/nvim/lua/config` and
+  plugin specs under `config/nvim/lua/plugins`.
 - lazy.nvim owns plugin management.
 
 ## Terminal
 
-- `tmux/` is linked to `~/.config/tmux`.
+- `config/tmux/` is linked to `~/.config/tmux`.
 - The installer can bootstrap TPM unless `DOTFILES_SKIP_TPM_BOOTSTRAP` is set.
-- `ghostty/` is linked to `~/.config/ghostty`.
+- `config/ghostty/` is linked to `~/.config/ghostty`.
 
 ## Automation
 
@@ -49,10 +49,10 @@ make check
 Useful focused checks:
 
 ```bash
-zsh -n zshrc
-zsh -n zsh/*.zsh
-git config --file gitconfig --list
-oh-my-posh init zsh --config ohmyposh/zen.toml
+zsh -n home/zshrc
+zsh -n home/zsh/*.zsh
+git config --file home/gitconfig --list
+oh-my-posh init zsh --config config/ohmyposh/zen.toml
 ```
 
 ## Known Tradeoffs