final using git

CLAUDE.md

@@ -105,8 +105,55 @@ Background process using fsnotify for continuous snapshot creation.
 | `onx switch <name>` | Switch workstreams | `git checkout` |
 | `onx sync` | Update with remote | `git pull --rebase` |
 | `onx push` | Push workstream | `git push` |
+| `onx push --stacked` | Push stacked diffs | N/A (advanced) |
 | `onx undo` | Undo last operation | `git reflog && reset` |
 
+## Push Workflows
+
+Onyx supports two push workflows to match different development styles:
+
+### Single-Branch Mode (Default) - Recommended for AI Development
+
+```bash
+onx push
+```
+
+**When to use:**
+- Default for all standard feature development
+- When creating traditional pull requests
+- For AI-assisted development sessions
+- When you want a clean remote repository UI
+
+**What happens:**
+- Pushes workstream as ONE branch named after the workstream
+- Example: `milestone-4` branch contains all commits
+- Remote UI shows single branch per workstream (clean)
+- Perfect for creating GitHub/Gitea pull requests
+
+**AI Development Guidance:**
+Use this mode by default. It provides the cleanest integration with standard Git workflows and PR creation tools.
+
+### Stacked Diffs Mode (Advanced)
+
+```bash
+onx push --stacked
+```
+
+**When to use:**
+- Large, complex features requiring incremental review
+- When each commit needs independent review/approval
+- Meta/Google-style stacked diff workflows
+- When explicitly requested by the user
+
+**What happens:**
+- Pushes EACH commit as a separate branch
+- Example: `onyx/workstreams/milestone-4/commit-1`, `commit-2`, etc.
+- Remote UI shows multiple branches (one per commit)
+- Each branch can have its own pull request
+
+**AI Development Guidance:**
+Only use when specifically requested or when the feature is complex enough to warrant incremental review. The additional branches may clutter the remote UI.
+
 ## Implementation Status
 
 This is currently a planning/prototype phase. The codebase contains:
@@ -117,6 +164,25 @@ This is currently a planning/prototype phase. The codebase contains:
 
 ## Development Guidelines
 
+### IMPORTANT: Dogfooding Policy
+
+**This repository uses Onyx for its own development.** All development work MUST use Onyx commands exclusively:
+
+- ✅ **Use `onx save -m "message"`** to commit changes (NOT `git commit`)
+- ✅ **Use `onx new <name>`** to create feature branches (NOT `git checkout -b`)
+- ✅ **Use `onx switch <name>`** to switch workstreams (NOT `git checkout`)
+- ✅ **Use `onx sync`** to update from remote (NOT `git pull`)
+- ✅ **Use `onx push`** to push to remote (NOT `git push`)
+- ✅ **Use `onx undo`** to undo operations (NOT `git reset`)
+- ✅ **Use `onx list`** to view workstreams (NOT `git branch`)
+
+**Exception:** Only use `git` commands for:
+- Initial remote setup (`git remote add`)
+- Creating pull requests via GitHub CLI (`gh pr create`)
+- Inspecting low-level Git state when debugging Onyx itself
+
+This dogfooding validates our user experience and ensures Onyx works correctly for real-world development.
+
 ### Code Style
 - Follow Go conventions and idioms
 - Use structured logging (planned: zap or logrus)