temp for tree extraction

BOOTSTRAP.md

@@ -0,0 +1,267 @@
+# Getting Started with Onyx
+
+Onyx is a next-generation version control system built on top of Git. These instructions will help you set up your repository using **only Onyx commands** - no Git knowledge required.
+
+## Create a New Repository
+
+Start a brand new project with Onyx:
+
+```bash
+# Navigate to your project directory
+cd /path/to/your/project
+
+# Initialize Onyx with a remote repository
+onx init --remote https://git.example.com/username/repo.git
+
+# Save your initial work
+onx save -m "Initial commit"
+
+# Push to the remote
+onx push
+```
+
+That's it! Your repository is now live.
+
+---
+
+## Push an Existing Repository
+
+Already have a project with files? Convert it to Onyx:
+
+```bash
+# Navigate to your existing project
+cd /path/to/existing/project
+
+# Initialize Onyx with your remote
+onx init --remote https://git.example.com/username/repo.git
+
+# Save all your existing work
+onx save -m "Initial commit - existing project"
+
+# Push everything to the remote
+onx push
+```
+
+---
+
+## Convert a Git Repository to Onyx
+
+Already using Git? Add Onyx on top:
+
+```bash
+# Navigate to your Git repository
+cd /path/to/git/repo
+
+# Initialize Onyx (remote already configured via Git)
+onx init
+
+# You're ready to use Onyx commands!
+onx save -m "Convert to Onyx"
+onx push
+```
+
+---
+
+## Common Next Steps
+
+After bootstrapping, here are the most common workflows:
+
+### Save Your Work
+```bash
+# Save changes (like git add + git commit)
+onx save -m "Add new feature"
+```
+
+### Push to Remote
+```bash
+# Push your work (default: single branch mode)
+onx push
+
+# Push as stacked diffs (advanced)
+onx push --stacked
+```
+
+### Create a New Workstream
+```bash
+# Create a new workstream for a feature (like git checkout -b)
+onx new feature-name
+
+# Or specify a base branch
+onx new feature-name --base main
+```
+
+### Switch Workstreams
+```bash
+# Switch to a different workstream (like git checkout)
+onx switch other-feature
+
+# Force switch even with uncommitted changes
+onx switch other-feature --force
+```
+
+### List Workstreams
+```bash
+# See all your workstreams (like git branch)
+onx list
+```
+
+### Sync with Remote
+```bash
+# Update from remote (like git pull --rebase)
+onx sync
+```
+
+### Undo Operations
+```bash
+# Undo your last operation
+onx undo
+```
+
+---
+
+## Understanding Workstreams
+
+Onyx uses **workstreams** instead of branches:
+
+- **Workstream** = A logical stream of work (like a feature branch)
+- **Automatic creation** = When you `onx init`, Onyx creates a workstream matching your current Git branch
+- **Clean workflow** = Each workstream manages a stack of commits
+
+### Push Modes
+
+Onyx supports two push workflows:
+
+#### Single-Branch Mode (Default - Recommended)
+```bash
+onx push
+```
+
+- Pushes workstream as **one branch** with all commits
+- Clean remote UI (one branch per workstream)
+- Perfect for traditional pull requests
+- **Best for most workflows**
+
+#### Stacked Diffs Mode (Advanced)
+```bash
+onx push --stacked
+```
+
+- Pushes **each commit** as a separate branch
+- Enables incremental review (Meta/Google style)
+- Each commit can have its own PR
+- More complex remote UI
+
+**Pro tip**: Stick with default `onx push` unless you need incremental review.
+
+---
+
+## Troubleshooting
+
+### "Not an Onyx repository"
+You need to run `onx init` first.
+
+### "No changes to commit"
+Your working directory is clean. Make some changes first.
+
+### "Workstream already exists"
+The workstream name is taken. Choose a different name or switch to the existing one.
+
+### "Non-fast-forward update"
+The remote has changes you don't have locally. Options:
+- Run `onx sync` to update first
+- Use `onx push --force` if you're sure (⚠️ use with caution)
+
+### "Remote validation failed"
+The remote doesn't exist or isn't configured. Check:
+- Is the remote URL correct?
+- Does the remote repository exist?
+- Do you have access permissions?
+
+---
+
+## Philosophy: No Git Required
+
+Onyx is designed to be **100% self-sufficient**. You never need to use Git commands:
+
+| What You Want | Git Command | Onyx Command |
+|---------------|-------------|--------------|
+| Save work | `git add . && git commit` | `onx save -m "msg"` |
+| Push | `git push` | `onx push` |
+| New branch | `git checkout -b` | `onx new` |
+| Switch branch | `git checkout` | `onx switch` |
+| List branches | `git branch` | `onx list` |
+| Update | `git pull --rebase` | `onx sync` |
+| Undo | `git reset`/`git reflog` | `onx undo` |
+| Clone | `git clone` | `onx clone` |
+
+**Note**: Git commands still work if you need them, but Onyx provides a better experience.
+
+---
+
+## Examples
+
+### Example 1: New Feature
+```bash
+# Start a new feature
+onx new user-authentication
+
+# Make changes to your code
+# ...
+
+# Save your work
+onx save -m "Add login form"
+
+# Make more changes
+# ...
+
+# Save again
+onx save -m "Add password validation"
+
+# Push to create a PR
+onx push
+```
+
+### Example 2: Quick Fix
+```bash
+# Create a hotfix workstream
+onx new hotfix-login-bug --base main
+
+# Fix the bug
+# ...
+
+# Save and push
+onx save -m "Fix login redirect bug"
+onx push
+```
+
+### Example 3: Complex Feature with Review
+```bash
+# Create feature workstream
+onx new complex-feature
+
+# Implement step 1
+onx save -m "Step 1: Database schema"
+
+# Implement step 2
+onx save -m "Step 2: API endpoints"
+
+# Implement step 3
+onx save -m "Step 3: Frontend UI"
+
+# Push as stacked diffs for incremental review
+onx push --stacked
+
+# Each commit gets its own branch for separate PRs
+```
+
+---
+
+## Need Help?
+
+- Read the full documentation: `README.md` and `CLAUDE.md`
+- Check the integration guide: `INTEGRATION.md`
+- Report issues: https://github.com/anthropics/claude-code/issues
+
+---
+
+**Welcome to Onyx - Version control that makes sense.**