Document shell-config architecture: one-pager for agents and new devs

[nichm]

Problem

Agents starting fresh (subagents, new sessions) have no overview of how shell-config works. They reinvent the wheel, use wrong commands, or modify the wrong files.

Solution

Add ARCHITECTURE.md (or a docs/ section) with:

• What shell-config is in 2 sentences
• Load order: .zshenv → .zshrc → init.sh → lib/core/ → lib/welcome/ → .zshrc.local
• Key entry points: init.sh, lib/core/loaders/, lib/welcome/main.sh
• Where to add things: loaders for tools, welcome modules for display, config/ for user settings
• Key env vars: SHELL_CONFIG_DIR, SHELL_DEBUG, WELCOME_MESSAGE_ENABLED
• How to test: cd tests && bats **/*.bats
• Line limit: 600 lines per shell file (hook enforced)

Bonus

Reference this file from the CLAUDE.md deployed by install.sh (#14) so agents can Read it for context.

[github-actions]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.