Merge pull request #3 from cardstack/feature/track-stop-symbols

Add track/stop commands and consistent local/remote symbols

Author: christse

.claude/CLAUDE.md

@@ -1,21 +1,29 @@
 # Boxel CLI - Claude Code Integration
 
+## GitHub Repository
+
+**Official repo:** https://github.com/cardstack/boxel-cli
+
+---
+
 ## How to Run Boxel Commands
 
-**IMPORTANT:** In this development repo, the `boxel` CLI is not globally installed. Always run commands using:
+After `npm install && npm run build`, use `npx boxel`:
 
 ```bash
-npm run dev -- <command> [args]
+npx boxel sync .
+npx boxel history ./workspace
+npx boxel profile add
 ```
 
-Examples:
+Or use `boxel` directly after `npm link`.
+
+**For development** (no rebuild needed after code changes):
 ```bash
-npm run dev -- sync .                    # NOT: boxel sync .
-npm run dev -- history ./workspace       # NOT: boxel history ./workspace
-npm run dev -- milestone ./workspace 1 -n "Name"
+npm run dev -- <command>
 ```
 
-The `--` separates npm arguments from the CLI arguments. All documentation below shows `boxel <command>` for brevity, but always use `npm run dev -- <command>` when executing.
+All documentation below shows `boxel <command>` for brevity.
 
 ---
 
@@ -43,67 +51,60 @@ The skill contains comprehensive Boxel development guidance including CardDef/Fi
 
 ## Onboarding Flow
 
-When you detect a new user (no `.env` file or first interaction), guide them through setup:
+When you detect a new user (no profile configured), guide them through setup:
 
-### Step 1: Check Environment
+### Step 1: Check Profile
 ```bash
-# Check if .env exists and has content
-cat .env 2>/dev/null || echo "NOT_CONFIGURED"
+npx boxel profile
 ```
 
-### Step 2: Prompt for Environment Choice
-If not configured, ask:
+If no profile exists, run the interactive setup:
 
+### Step 2: Add a Profile
+```bash
+npx boxel profile add
 ```
-Welcome to Boxel CLI! Let's get you set up.
-
-Which environment do you want to use?
-
-1. **Production** (app.boxel.ai) - Live Boxel
-2. **Staging** (realms-staging.stack.cards) - Development/testing
 
-You'll need your Boxel username and password (same as web login).
+This launches an interactive wizard that:
+1. Asks for environment (Production or Staging)
+2. Asks for username and password
+3. Creates the profile in `~/.boxel-cli/profiles.json`
 
-Your username is your Boxel handle (e.g., `aallen90`, `ctse`). Find it in:
-- **Account panel**: shown as `@username:stack.cards`
-- **Workspace URLs**: `app.boxel.ai/username/workspace-name`
+**Non-interactive option (CI/automation only):**
+```bash
+# Use environment variable to avoid exposing password in shell history
+BOXEL_PASSWORD="password" npx boxel profile add -u @username:boxel.ai -n "My Prod Account"
 ```
 
-### Step 3: Create .env
-Based on their choice:
-
-**Production:**
-```env
-MATRIX_URL=https://matrix.boxel.ai
-MATRIX_USERNAME=<ask for username>
-MATRIX_PASSWORD=<ask for password>
-REALM_SERVER_URL=https://app.boxel.ai/
-```
+> **Security Note:** Avoid passing passwords via `-p` flag as they appear in shell history and process listings. Use the interactive wizard or `BOXEL_PASSWORD` environment variable.
 
-**Staging:**
-```env
-MATRIX_URL=https://matrix-staging.stack.cards
-MATRIX_USERNAME=<ask for username>
-MATRIX_PASSWORD=<ask for password>
-REALM_SERVER_URL=https://realms-staging.stack.cards/
+### Step 3: Verify & List Workspaces
+```bash
+npx boxel list
 ```
 
-### Step 4: Verify & List Workspaces
+### Step 4: First Sync
+Help them sync their first workspace:
 ```bash
-npm install
-npm run dev -- list
+npx boxel sync @username/workspace ./workspace-name
 ```
 
-### Step 5: First Sync
-Help them sync their first workspace:
+### Switching Between Profiles
 ```bash
-npm run dev -- sync @username/workspace ./workspace-name
+npx boxel profile list              # See all profiles (★ = active)
+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
@@ -119,7 +120,7 @@ Complete restore workflow:
 
 ### `/sync` - Smart Sync
 Context-aware bidirectional sync:
-- After local edits → `--prefer-local`
+- After local edits or track → `--prefer-local`
 - After server changes → `--prefer-remote`
 - After restore → `--prefer-local` (essential for syncing deletions)
 
@@ -145,7 +146,17 @@ boxel sync . --delete             # Sync deletions both ways
 boxel sync . --dry-run            # Preview only
 ```
 
-### Watch
+### Track ⇆ (Local File Watching)
+```bash
+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
+```
+
+**Use track when:** Editing locally in IDE/VS Code. Creates checkpoints as you save files.
+**Symbol:** ⇆ (horizontal arrows = local changes)
+
+### Watch ⇅ (Remote Server Watching)
 ```bash
 boxel watch                       # Watch all configured realms (from .boxel-workspaces.json)
 boxel watch .                     # Watch single workspace
@@ -154,6 +165,14 @@ boxel watch . -i 5 -d 3           # Active: 5s interval, 3s debounce
 boxel watch . -q                  # Quiet mode
 ```
 
+**Use watch when:** Others are editing in Boxel web UI. Pulls their changes and creates checkpoints.
+**Symbol:** ⇅ (vertical arrows = remote server changes)
+
+### Stop
+```bash
+boxel stop                        # Stop all running watch (⇅) and track (⇆) processes
+```
+
 **Multi-realm watching:** Useful when code lives in one realm and data in another. Each realm gets its own checkpoint tracking and debouncing.
 
 ### Realms (Multi-Realm Configuration)
@@ -175,6 +194,7 @@ boxel history .                   # View checkpoints
 boxel history . -r                # Interactive restore
 boxel history . -r 3              # Quick restore to #3
 boxel history . -r abc123         # Restore by hash
+boxel history . -m "Message"      # Create checkpoint with custom message
 ```
 
 ### Skills
@@ -186,6 +206,23 @@ boxel skills --disable "Name"     # Disable a skill
 boxel skills --export ./project   # Export as Claude commands
 ```
 
+### Profile (Authentication)
+```bash
+boxel profile                     # Show current active profile
+boxel profile list                # List all saved profiles (★ = active)
+boxel profile add                 # Interactive wizard to add profile (recommended)
+# Non-interactive: use BOXEL_PASSWORD env var instead of -p flag for security
+boxel profile switch <username>   # Switch profile (partial match OK)
+boxel profile remove <profile-id> # Remove a profile
+boxel profile migrate             # Migrate from old .env file
+```
+
+**Profile IDs:** Use Matrix format `@username:domain`
+- Production: `@username:boxel.ai`
+- Staging: `@username:stack.cards`
+
+**Storage:** Profiles stored in `~/.boxel-cli/profiles.json` (permissions: 0600)
+
 ### Other
 ```bash
 boxel list                        # List workspaces
@@ -237,7 +274,19 @@ boxel skills --export .      # Re-export to .claude/commands/
 
 ## Key Workflows
 
-### Active Development Session
+### 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)
 ```bash
 /watch                            # Starts with 5s interval
 # ... edit in Boxel UI or locally ...
@@ -373,8 +422,8 @@ Watch waits for changes to settle:
 ### 4. Checkpoint Classification
 - `[MAJOR]` - New files, deleted files, .gts changes, >3 files
 - `[minor]` - Small updates to existing .json files
-- `LOCAL` (↑) - Changes you pushed
-- `SERVER` (↓) - External changes from web UI
+- `LOCAL` ⇆ - Changes from local edits (track command)
+- `SERVER` ⇅ - External changes from web UI (watch command)
 
 ---
 
@@ -403,6 +452,65 @@ Commands accept:
 
 ---
 
+## Understanding Boxel URLs (Card IDs)
+
+When a user shares a URL like:
+```
+https://app.boxel.ai/tribecaprep/employee-handbook/Document/d8341312-f3a0-442b-a2e5-49c5cdd84695
+```
+
+**This is a Card ID, not a fetchable URL!**
+
+### How to Parse Boxel URLs
+
+| URL Part | Meaning |
+|----------|---------|
+| `app.boxel.ai` | Production server |
+| `tribecaprep` | User/organization |
+| `employee-handbook` | Realm/workspace name |
+| `Document/d8341312-...` | Card type and instance path |
+
+### NEVER Use WebFetch on Boxel URLs
+
+- Boxel realms are **usually private** and require Matrix authentication
+- WebFetch will fail with 401/403 errors
+- The user is referencing content **they expect you to have locally**
+
+### Finding the Local Copy
+
+If the user references a Boxel URL, the file is likely already synced to the local workspace:
+
+1. **Parse the path**: `Document/d8341312-f3a0-442b-a2e5-49c5cdd84695` → local path is `Document/d8341312-f3a0-442b-a2e5-49c5cdd84695.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/
+```
+
+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"
+
+**Do this:**
+```
+# Look for local file
+Read ./Document/abc123.json
+```
+
+**NOT this:**
+```
+# This will FAIL - private realm
+WebFetch https://app.boxel.ai/tribecaprep/employee-handbook/Document/abc123
+```
+
+---
+
 ## API Reference
 
 | Endpoint | Method | Purpose |
@@ -433,13 +541,15 @@ Headers:
 ## Troubleshooting
 
 ### "Authentication failed"
-- Check credentials in `.env`
-- Verify you can log into Boxel web
-- For staging: use `matrix-staging.stack.cards`
+- Check active profile: `boxel profile`
+- Verify credentials: `boxel profile list`
+- Verify you can log into Boxel web with same credentials
+- For staging: ensure profile uses `@username:stack.cards`
 
 ### "No workspace found"
 - Run `boxel list` to see workspaces
 - Use full URL for first sync
+- Ensure correct profile is active for the environment
 
 ### Files keep reverting after restore
 - Stop watch before restoring
@@ -448,4 +558,8 @@ Headers:
 ### Watch not detecting changes
 - Check interval setting
 - Verify server URL
-- Check JWT auth
+- Check active profile: `boxel profile`
+
+### Switching environments (prod/staging)
+- Add profiles for each environment
+- Switch with: `boxel profile switch <username>`