Add batch upload and track --push features

Features:
- Add batch upload via /_atomic endpoint for efficient multi-file uploads
- Add --push flag to track command for automatic server sync
- Cache JWT at startup in long-running processes (track, watch)
- Add -v/--verbose flag to sync, track, watch, push, pull commands

Batch upload features:
- Efficient batching with configurable batch size and payload limits
- Fallback strategy: full batch → half batches → individual uploads
- Verbose logging shows file lists, payload sizes, server responses
- Proper error handling with detailed error messages from /_atomic

Documentation:
- Update CLAUDE.md with track --push workflow
- Update README with verbose mode section and examples
- Document real-time local-to-server sync workflow

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: christse

.claude/CLAUDE.md

@@ -99,12 +99,6 @@ npx boxel profile switch username   # Switch by partial match
 
 ## Available Skills
 
-### `/track` - Track Local Edits
-Starts `boxel track` to auto-checkpoint local file changes:
-- Creates checkpoints as you save files in IDE
-- **IMPORTANT:** Track creates LOCAL checkpoints only
-- **After editing, run `boxel sync . --prefer-local` to push to server**
-
 ### `/watch` - Smart Watch
 Starts `boxel watch` with intelligent interval based on context:
 - **Active development** (5s interval, 3s debounce): When editing files
@@ -120,7 +114,7 @@ Complete restore workflow:
 
 ### `/sync` - Smart Sync
 Context-aware bidirectional sync:
-- After local edits or track → `--prefer-local`
+- After local edits → `--prefer-local`
 - After server changes → `--prefer-remote`
 - After restore → `--prefer-local` (essential for syncing deletions)
 
@@ -151,18 +145,23 @@ boxel sync . --dry-run            # Preview only
 boxel track .                     # Track local edits, auto-checkpoint as you save
 boxel track . -d 5 -i 30          # 5s debounce, 30s min between checkpoints
 boxel track . -q                  # Quiet mode
+boxel track . --push              # Auto-push changes to server (batch upload)
+boxel track . --push -v           # Push with verbose logging
 ```
 
 **Use track when:** Editing locally in IDE/VS Code. Creates checkpoints as you save files.
 **Symbol:** ⇆ (horizontal arrows = local changes)
 
+**--push mode:** Automatically batch uploads changes to the server after each checkpoint using the `/_atomic` endpoint. Efficient for real-time sync workflows.
+
 ### Watch ⇅ (Remote Server Watching)
 ```bash
 boxel watch                       # Watch all configured realms (from .boxel-workspaces.json)
 boxel watch .                     # Watch single workspace
 boxel watch . ./other-realm       # Watch multiple realms simultaneously
 boxel watch . -i 5 -d 3           # Active: 5s interval, 3s debounce
 boxel watch . -q                  # Quiet mode
+boxel watch . -v                  # Verbose logging
 ```
 
 **Use watch when:** Others are editing in Boxel web UI. Pulls their changes and creates checkpoints.
@@ -238,6 +237,7 @@ boxel gather . -s /path/to/repo                          # Pull from GitHub repo
 ```
 
 **Share** copies workspace state to a GitHub repo branch:
+- Copies to repo root by default (use `--subfolder` to target a specific directory)
 - Preserves repo-level files (package.json, LICENSE, README, etc.)
 - Skips realm-specific files (.realm.json, index.json, cards-grid.json)
 - Creates branch and commits changes
@@ -274,25 +274,21 @@ boxel skills --export .      # Re-export to .claude/commands/
 
 ## Key Workflows
 
-### Local Development with Track (IDE/Agent Editing)
-```bash
-boxel track .                     # Start tracking local edits (auto-checkpoints)
-# ... edit files in IDE or with Claude ...
-# Track creates LOCAL checkpoints as you save
-
-# IMPORTANT: When ready to push changes to Boxel server:
-boxel sync . --prefer-local       # Push your local changes to server
-```
-
-**Remember:** Track does NOT sync to server automatically - it only creates local checkpoints. Always run `sync --prefer-local` when you want your changes live on the server.
-
-### Active Development Session (Watching Server)
+### Active Development Session
 ```bash
 /watch                            # Starts with 5s interval
 # ... edit in Boxel UI or locally ...
 /sync                             # Push/pull changes
 ```
 
+### Real-Time Local-to-Server Sync
+```bash
+boxel track . --push -d 2 -i 5    # Track + auto-push with 2s debounce, 5s interval
+# Edit files in IDE - changes auto-sync to server via batch upload
+```
+
+**Use this when:** You want instant sync to server as you edit locally. Uses the efficient `/_atomic` batch upload endpoint.
+
 ### Undo Server Changes (Restore)
 ```bash
 boxel history .                   # Find checkpoint

.claude/commands/track.md

@@ -0,0 +1,48 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(npm run dev:*)",
+      "Bash(ls:*)",
+      "Bash(pdftotext:*)",
+      "Bash(python3:*)",
+      "Bash(npm run build:*)",
+      "Bash(git checkout:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(DEBUG=1 timeout 30 npm run dev:*)",
+      "Bash(pkill:*)",
+      "Bash(code:*)",
+      "Bash(open:*)",
+      "Bash(npm run:*)",
+      "Bash(git push:*)",
+      "Bash(npx boxel:*)",
+      "Bash(git remote set-url:*)",
+      "Bash(npm install:*)",
+      "Bash(git fetch:*)",
+      "Bash(git stash:*)",
+      "Bash(git pull:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git status:*)",
+      "Bash(git branch:*)",
+      "Bash(xargs:*)",
+      "Bash(cat:*)",
+      "Bash(echo \"card definitions\" ls ./steady-loon/boxel-ai-website/SampleCard/*/*.json)",
+      "Bash(zip:*)",
+      "Bash(find:*)",
+      "WebFetch(domain:images.pexels.com)",
+      "WebSearch",
+      "Bash(# Copy all instance directories explicitly SOURCE=\"\"/Users/chris/Documents/code/boxel-cli/steady-loon/boxel-ai-website/SampleCard\"\" DEST=\"\"/Users/chris/Documents/code/boxel-cli/hilarious-marmoset/placeholders\"\" for dir in AiImageCard AnalyticsDashboard BlogPost BrochureCard BudgetLineItemCard CodeReview ConferenceCard CourseModuleCard DesignAssetCard EventTicketCard ExpenseReportCard FitnessActivityCard FlashcardCard HotelRoomCard InventoryItemCard Invoice LeaseAgreementCard MaintenanceRequestCard MedicationReminderCard MeetingRoomCard PatientAppointmentCard PodcastEpisodeCard Product ProjectTracker PropertyListingCard RecipeCardCard RestaurantMenuItemCard SalesCrm ShipmentTrackingCard StockTickerCard StudentGradeCard StudyGuideCard SubscriptionPlanCard TimeEntryCard TradingCardCard TripItineraryCard VideoContentCard; do cp -rf \"\"$SOURCE/$dir\"\" \"\"$DEST/\"\" done echo \"\"Directories copied. Listing new directories:\"\" ls -d \"\"$DEST\"\"/*/)",
+      "Bash(# List the orphan JSON files in placeholders root \\(not in subdirectories\\) ls /Users/chris/Documents/code/boxel-cli/hilarious-marmoset/placeholders/*.json)",
+      "Bash(# Delete all orphan JSON files from placeholders root rm /Users/chris/Documents/code/boxel-cli/hilarious-marmoset/placeholders/*.json echo \"\"Deleted orphan JSON files\"\" ls /Users/chris/Documents/code/boxel-cli/hilarious-marmoset/placeholders/*.json)",
+      "Bash(lsof:*)",
+      "Bash(xattr:*)",
+      "Bash(ssh-add:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(npx tsc:*)",
+      "Bash(npx tsx:*)",
+      "Bash(curl:*)"
+    ]
+  }
+}

.claude/settings.local.json

@@ -205,13 +205,16 @@ boxel pull <url> ./local          # One-way pull (remote → local)
 boxel track .                     # Track local edits, auto-checkpoint
 boxel track . -d 5 -i 30          # 5s debounce, 30s min between checkpoints
 boxel track . -q                  # Quiet mode
+boxel track . --push              # Auto-push to server via batch upload
+boxel track . --push -v           # Push with verbose logging
 
 # Watch REMOTE server changes (pull external updates)
 boxel watch .                     # Watch single workspace (30s default)
 boxel watch . ./other-realm       # Watch multiple realms
 boxel watch                       # Watch all configured realms
 boxel watch . -i 5 -d 3           # 5s interval, 3s debounce
 boxel watch . -q                  # Quiet mode
+boxel watch . -v                  # Verbose logging
 
 # Stop all watchers and trackers
 boxel stop                        # Stops all running watch (⇅) and track (⇆) processes
@@ -225,6 +228,7 @@ boxel status . --pull             # Auto-pull changes
 | Command | Symbol | Direction | Purpose |
 |---------|--------|-----------|---------|
 | `track` | ⇆ | Local → Checkpoints | Backup your IDE edits as you type |
+| `track --push` | ⇆ | Local → Server | Real-time sync to server (batch upload) |
 | `watch` | ⇅ | Server → Local | Pull external changes from Boxel web UI |
 
 ### History & Checkpoints
@@ -301,14 +305,9 @@ boxel skills --export .           # Export to .claude/commands/
 boxel track .                     # Start tracking local edits
 # In another terminal or IDE, edit files...
 # Checkpoints created automatically as you save
-
-# IMPORTANT: Track creates LOCAL checkpoints only!
-# When ready to push changes to Boxel server:
 boxel sync . --prefer-local       # Push changes to server
 ```
 
-**Remember:** `track` does NOT sync to server - it only creates local checkpoints for safety. Always run `sync --prefer-local` when you want your changes live.
-
 ### Active Development (with edit lock)
 ```bash
 boxel edit . my-card.gts          # Lock file (if watch is running)
@@ -508,6 +507,26 @@ cat ./Type/card-id.json
 | Files reverting after restore | Stop watch first, use `--prefer-local` after |
 | Watch not detecting changes | Check interval, verify workspace URL |
 | Definition changes not reflected | `boxel touch . Instance/file.json` |
+| Need more details on errors | Add `-v` or `--verbose` flag |
+
+### Verbose Mode
+
+Most commands support verbose logging with `-v` or `--verbose`:
+
+```bash
+boxel sync . --prefer-local -v    # Detailed sync logging
+boxel track . --push -v           # See batch upload details
+boxel watch . -v                  # JWT and polling info
+boxel push ./local <url> -v       # Upload debugging
+boxel pull <url> ./local -v       # Download debugging
+```
+
+Verbose output shows:
+- Matrix authentication details
+- JWT acquisition timing
+- Batch upload operations (file lists, payload sizes)
+- Server response status codes
+- Error details from `/_atomic` endpoint
 
 ---