Add batch upload and track --push features

.claude/CLAUDE.md

@@ -49,6 +49,37 @@ The skill contains comprehensive Boxel development guidance including CardDef/Fi
 
 **When a user opens this repo, check if they need onboarding first!**
 
+## Local Workspace Directory Convention
+
+Boxel workspaces are synced to a dedicated directory outside of git repos (to avoid conflicts with multi-user PRs):
+
+```
+~/boxel-workspaces/
+├── boxel.ai/                    # Production realm server
+│   ├── acme-corp/               # User/org
+│   │   ├── project-atlas/       # Workspace
+│   │   └── personal/
+│   └── jsmith/
+└── stack.cards/                 # Staging realm server
+    └── jsmith/
+        └── sandbox/
+```
+
+**Structure:** `~/boxel-workspaces/{realm-server}/{user}/{workspace}`
+
+**First sync example:**
+```bash
+boxel sync @acme-corp/project-atlas ~/boxel-workspaces/boxel.ai/acme-corp/project-atlas
+```
+
+**Why this structure:**
+- Keeps Boxel workspaces separate from git repos (different sync/PR workflows)
+- Groups by realm server to avoid name collisions across environments
+- Groups by user to support multiple accounts
+- Clear mapping from Boxel URL to local path
+
+---
+
 ## Onboarding Flow
 
 When you detect a new user (no profile configured), guide them through setup:
@@ -84,9 +115,10 @@ npx boxel list
 ```
 
 ### Step 4: First Sync
-Help them sync their first workspace:
+Help them sync their first workspace to the standard location:
 ```bash
-npx boxel sync @username/workspace ./workspace-name
+# Structure: ~/boxel-workspaces/{realm-server}/{user}/{workspace}
+npx boxel sync @username/workspace ~/boxel-workspaces/boxel.ai/username/workspace
 ```
 
 ### Switching Between Profiles
@@ -99,12 +131,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 +146,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,10 +177,15 @@ 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)
+**Direction:** Local only (unless `--push` is used)
+
+**--push mode:** Automatically batch uploads changes to the server after each checkpoint using the `/_atomic` endpoint. This is how you push local edits to the server in real-time.
 
 ### Watch ⇅ (Remote Server Watching)
 ```bash
@@ -163,10 +194,12 @@ 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.
 **Symbol:** ⇅ (vertical arrows = remote server changes)
+**Direction:** Server → Local only (pull, never pushes)
 
 ### Stop
 ```bash
@@ -238,6 +271,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 +308,23 @@ 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.
+
+**Manual sync while tracking:** You can run `boxel sync . --prefer-local` anytime while track --push is running to force an immediate sync (useful after interactive edits or if you want to push without waiting for debounce).
+
 ### Undo Server Changes (Restore)
 ```bash
 boxel history .                   # Find checkpoint
@@ -456,7 +488,7 @@ Commands accept:
 
 When a user shares a URL like:
 ```
-https://app.boxel.ai/tribecaprep/employee-handbook/Document/d8341312-f3a0-442b-a2e5-49c5cdd84695
+https://app.boxel.ai/acme-corp/project-atlas/Document/d8341312-f3a0-442b-a2e5-49c5cdd84695
 ```
 
 **This is a Card ID, not a fetchable URL!**
@@ -466,8 +498,8 @@ https://app.boxel.ai/tribecaprep/employee-handbook/Document/d8341312-f3a0-442b-a
 | URL Part | Meaning |
 |----------|---------|
 | `app.boxel.ai` | Production server |
-| `tribecaprep` | User/organization |
-| `employee-handbook` | Realm/workspace name |
+| `acme-corp` | User/organization |
+| `project-atlas` | Realm/workspace name |
 | `Document/d8341312-...` | Card type and instance path |
 
 ### NEVER Use WebFetch on Boxel URLs
@@ -478,35 +510,34 @@ https://app.boxel.ai/tribecaprep/employee-handbook/Document/d8341312-f3a0-442b-a
 
 ### Finding the Local Copy
 
-If the user references a Boxel URL, the file is likely already synced to the local workspace:
+If the user references a Boxel URL, map it to the local workspace path:
 
-1. **Parse the path**: `Document/d8341312-f3a0-442b-a2e5-49c5cdd84695` → local path is `Document/d8341312-f3a0-442b-a2e5-49c5cdd84695.json`
+1. **Map URL to local path** using the directory convention:
+   - URL: `https://app.boxel.ai/acme-corp/project-atlas/Document/abc123`
+   - Local: `~/boxel-workspaces/boxel.ai/acme-corp/project-atlas/Document/abc123.json`
 
-2. **Search the workspace**:
-```bash
-# Find by card ID
-find . -name "d8341312-f3a0-442b-a2e5-49c5cdd84695*"
-
-# Or search for the card type folder
-ls ./Document/
-```
+2. **Parse the components**:
+   - `app.boxel.ai` → realm server `boxel.ai`
+   - `acme-corp` → user
+   - `project-atlas` → workspace
+   - `Document/abc123` → card path (add `.json`)
 
 3. **Read the local file** using the Read tool
 
 ### Example Workflow
 
-User says: "Check the handbook at https://app.boxel.ai/tribecaprep/employee-handbook/Document/abc123"
+User says: "Check the docs at https://app.boxel.ai/acme-corp/project-atlas/Document/abc123"
 
 **Do this:**
 ```
-# Look for local file
-Read ./Document/abc123.json
+# Map URL to local path using convention
+Read ~/boxel-workspaces/boxel.ai/acme-corp/project-atlas/Document/abc123.json
 ```
 
 **NOT this:**
 ```
 # This will FAIL - private realm
-WebFetch https://app.boxel.ai/tribecaprep/employee-handbook/Document/abc123
+WebFetch https://app.boxel.ai/acme-corp/project-atlas/Document/abc123
 ```
 
 ---

.claude/commands/setup.md

@@ -33,7 +33,7 @@ This wizard will:
 
 Ask the user for:
 - **Environment**: Production (app.boxel.ai) or Staging (realms-staging.stack.cards)
-- **Username**: Their Boxel handle (e.g., `aallen90`, `ctse`). Found in Account panel as `@username:stack.cards` or in workspace URLs like `app.boxel.ai/username/workspace-name`
+- **Username**: Their Boxel handle (e.g., `jsmith`, `acme-corp`). Found in Account panel as `@username:stack.cards` or in workspace URLs like `app.boxel.ai/username/workspace-name`
 - **Password**: Same as Boxel web login
 
 Then run (using environment variable for security):
@@ -56,9 +56,10 @@ npx boxel list
 ```
 
 ### 4. First Sync
-Help them sync a workspace:
+Help them sync a workspace to the standard location:
 ```bash
-npx boxel sync @username/workspace ./workspace-name
+# Structure: ~/boxel-workspaces/{realm-server}/{user}/{workspace}
+npx boxel sync @username/workspace ~/boxel-workspaces/boxel.ai/username/workspace
 ```
 
 ## Profile Management

.claude/settings.local.json

@@ -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:*)"
+    ]
+  }
+}