Improve documentation coverage and clarity

[slifty]

Problem

Documentation is incomplete and doesn't cover many important aspects of the dotfiles system.

Specific Gaps

1. README.md Issues

• Line 1 still says "slifty's dotfiles" (not generic/reusable language)
• No documentation about re-running bootstrap safely
• No troubleshooting guide
• No explanation of AGENTS.md/CLAUDE.md purpose
• Missing information about what happens during bootstrap

2. Topic Documentation

Only 4 topics have READMEs (python, local, ots, thunderbird). Most topics lack documentation:

• What does each topic configure?
• What applications/tools are affected?
• Any manual steps after install?
• Configuration locations

3. Missing Guides

• No troubleshooting section
• No guide for selective installation
• No explanation of the bootstrap process flow
• No documentation of common issues and solutions

Impact

• New users don't understand what the dotfiles will do
• Hard to debug when things go wrong
• Contributors don't know where to add features
• Maintenance burden when knowledge is only in code

Recommended Improvements

1. Update README.md

• Make title and intro more generic
• Add section explaining AGENTS.md purpose
• Document that bootstrap.sh can be safely re-run (once idempotency is fixed)
• Add troubleshooting section with common issues
• Document bootstrap process flow more clearly

2. Add Topic READMEs

Create README.md in major topics explaining:

• What the topic configures
• What applications are involved
• Any manual steps required
• Where configurations are stored

Priority topics:

• git/ - Explain aliases, signing, custom config
• zsh/ - Explain Oh My ZSH setup, themes, plugins
• macos/ - Explain what system preferences are changed
• docker/ - Explain Docker setup
• node/, python/, ruby/ - Explain version management

3. Add Troubleshooting Guide

Common issues to document:

• Bootstrap fails midway
• Permission errors
• Missing environment variables
• Brew install failures
• GPG key setup issues

4. Document AGENTS.md

Add a section in README explaining what AGENTS.md is for and how AI assistants use it.

Success Criteria

• New users understand what will happen before running bootstrap
• Each major topic has a README
• Common issues have documented solutions
• README is welcoming to potential forkers

Priority

MEDIUM - Important for usability and maintainability