## 1. Create docs/ directory with dedicated pages
- [ ] 1.1 Create `docs/index.md` with a table of contents for all docs/ pages
- [ ] 1.2 Create `docs/cli.md` with full CLI flag reference and examples
- [ ] 1.3 Create `docs/configuration.md` with config options, presets, changelog, commit types, tag tracking
- [ ] 1.4 Create `docs/release-workflow.md` with release-please flow, direct-push, bypass token, reference implementation
- [ ] 1.5 Create `docs/best-practices.md` with release, CI gating, commit, and pinning best practices
- [ ] 1.6 Create `docs/ci-cd-patterns.md` with skip-bump, read version, JSON output, and how-it-works
- [ ] 1.7 Create `docs/migration-v4.md` with v5.0.0 and v5.2.0 changes, scripting migration, staying on v4
- [ ] 1.8 Create `docs/troubleshooting.md` with all error entries
## 2. Trim README.md
- [ ] 2.1 Keep Why, Quick Start, Installation (brief), Usage (brief flag list with link to docs/cli.md), Configuration (brief with link to docs/configuration.md)
- [ ] 2.2 Add a "Quick Reference" section linking to each docs/ page
- [ ] 2.3 Update the Contributing section to note the docs/ structure
- [ ] 2.4 Remove all sections that were moved to docs/ pages
- [ ] 2.5 Update internal anchor links that changed due to restructuring
- [ ] 2.6 Verify all cross-links between README and docs/ work
## 3. Update CONTRIBUTING.md
- [ ] 3.1 Add note about `docs/` directory for documentation contributions
- [ ] 3.2 Update any stale references to README sections
## 4. Verify and commit
- [ ] 4.1 Review all docs for readability and consistency
- [ ] 4.2 Commit and create PR