Merge pull request #15 from cardstack/pr-review/command-restructure-and-defaults

Restructure CLI commands, add default workspace root, update docs

Author: christse

.claude/CLAUDE.md

@@ -80,13 +80,13 @@ BOXEL_PASSWORD="password" npx boxel profile add -u @username:boxel.ai -n "My Pro
 
 ### Step 3: Verify & List Workspaces
 ```bash
-npx boxel list
+npx boxel workspace-list
 ```
 
-### Step 4: First Sync
-Help them sync their first workspace:
+### Step 4: First Pull
+Help them pull their first workspace (defaults to `~/boxel-workspaces/`):
 ```bash
-npx boxel sync @username/workspace ./workspace-name
+npx boxel pull https://app.boxel.ai/username/workspace/
 ```
 
 ### Switching Between Profiles
@@ -99,33 +99,32 @@ npx boxel profile switch username   # Switch by partial match
 
 ## Local Workspace Organization
 
-When syncing multiple workspaces locally, organize them by **domain/username/realm** to mirror the Matrix ID structure (`@username:domain`):
+The CLI stores synced workspaces under `~/boxel-workspaces/` by default, organized by **realm-server-hostname/username/realm**:
 
 ```
-boxel-workspaces/
-├── boxel.ai/                      # Production domain
-│   └── acme-corp/                 # Username
-│       ├── personal/              # Realm
+~/boxel-workspaces/                          # Default root (all platforms)
+├── app.boxel.ai/                            # Production realm server
+│   └── acme-corp/
+│       ├── personal/
 │       ├── project-atlas/
 │       └── inventory-tracker/
-└── stack.cards/                   # Staging domain
+└── realms-staging.stack.cards/              # Staging realm server
     └── acme-corp/
         └── sandbox/
 ```
 
+**Default root:** `~/boxel-workspaces/` on macOS, Linux, and Windows. Override by passing an explicit local path to `pull` or `sync`.
+
 **Benefits:**
-- Clear separation between production and staging environments
-- Matches the `@username:domain` profile ID format
-- Easy to identify which profile/environment a workspace belongs to
-- Supports multiple users on the same machine
+- Full realm server hostname as folder name eliminates staging/production ambiguity
+- Each environment is clearly identifiable by its path
+- No collision between realms on different servers
 
-**First-time sync to this structure:**
+**First-time sync:**
 ```bash
-# Production workspace
-boxel pull https://app.boxel.ai/acme-corp/project-atlas/ ./boxel-workspaces/boxel.ai/acme-corp/project-atlas
-
-# Staging workspace
-boxel pull https://realms-staging.stack.cards/acme-corp/sandbox/ ./boxel-workspaces/stack.cards/acme-corp/sandbox
+# The CLI automatically places workspaces under ~/boxel-workspaces/
+boxel pull https://app.boxel.ai/acme-corp/project-atlas/
+boxel pull https://realms-staging.stack.cards/acme-corp/sandbox/
 ```
 
 ---
@@ -160,8 +159,8 @@ Context-aware bidirectional sync:
 ### `/repair` - Realm Metadata/Card Repair
 Use when workspaces show missing icon/background, wrong display name, or fail to open due to broken `index.json`/`cards-grid.json` links.
 - Read `.claude/commands/repair.md` for the step-by-step repair flow.
-- `boxel repair-realm <url>` repairs one realm
-- `boxel repair-realms` repairs all owned realms (excluding `personal` by default)
+- `boxel doctor repair-realm <url>` repairs one realm
+- `boxel doctor repair-realms` repairs all owned realms (excluding `personal` by default)
 - Also reconciles Matrix account data (`app.boxel.realms`) unless disabled
 
 ---
@@ -252,12 +251,12 @@ boxel stop                        # Stop all running watch (⇅) and track (⇆)
 ### Realms (Multi-Realm Configuration)
 ```bash
 boxel realms                      # List configured realms
-boxel realms --init               # Create .boxel-workspaces.json
-boxel realms --add ./path         # Add a realm
-boxel realms --add ./code --purpose "Card definitions" --patterns "*.gts" --default
-boxel realms --add ./data --purpose "Data instances" --card-types "BlogPost,Product"
-boxel realms --llm                # Output LLM guidance for file placement
-boxel realms --remove ./path      # Remove a realm
+boxel realms init               # Create .boxel-workspaces.json
+boxel realms add ./path         # Add a realm
+boxel realms add ./code --purpose "Card definitions" --patterns "*.gts" --default
+boxel realms add ./data --purpose "Data instances" --card-types "BlogPost,Product"
+boxel realms llm                # Output LLM guidance for file placement
+boxel realms remove ./path      # Remove a realm
 ```
 
 **File placement guidance:** The `--llm` output tells Claude which realm to use for different file types and card types.
@@ -299,11 +298,11 @@ boxel profile migrate             # Migrate from old .env file
 
 ### Other
 ```bash
-boxel list                        # List workspaces
+boxel workspace-list                        # List workspaces
 boxel create endpoint "Name"      # Create workspace
-boxel consolidate-workspaces .    # Move legacy local dirs into domain/owner/realm
-boxel repair-realm <url>          # Repair one realm metadata/starter cards
-boxel repair-realms               # Batch repair all owned realms
+boxel doctor consolidate-workspaces      # Fix workspace dirs (defaults to ~/boxel-workspaces/)
+boxel doctor repair-realm <url>          # Repair one realm metadata/starter cards
+boxel doctor repair-realms               # Batch repair all owned realms
 boxel pull <url> ./local          # One-way pull
 boxel push ./local <url>          # One-way push
 ```
@@ -419,14 +418,14 @@ When working with multiple realms (e.g., code + data separation):
 
 ```bash
 # Configure realms once
-boxel realms --add ./code-realm --purpose "Card definitions" --patterns "*.gts" --default
-boxel realms --add ./data-realm --purpose "Content instances" --card-types "BlogPost,Product"
+boxel realms add ./code-realm --purpose "Card definitions" --patterns "*.gts" --default
+boxel realms add ./data-realm --purpose "Content instances" --card-types "BlogPost,Product"
 
 # Watch all configured realms
 boxel watch
 
 # Check where to put a new file
-boxel realms --llm
+boxel realms llm
 ```
 
 **File placement heuristics:**
@@ -675,7 +674,7 @@ The `/_atomic` endpoint supports batch file operations that succeed or fail atom
 - For staging: ensure profile uses `@username:stack.cards`
 
 ### "No workspace found"
-- Run `boxel list` to see workspaces
+- Run `boxel workspace-list` to see workspaces
 - Use full URL for first sync
 - Ensure correct profile is active for the environment
 

.claude/commands/repair.md

@@ -10,18 +10,18 @@ Use this workflow when a workspace has any of these symptoms:
 
 ```bash
 # Inspect one realm without mutating
-boxel repair-realm <workspace-url> --dry-run
+boxel doctor repair-realm <workspace-url> --dry-run
 
 # Repair one realm
-boxel repair-realm <workspace-url>
+boxel doctor repair-realm <workspace-url>
 
 # Repair all realms owned by active profile user
-boxel repair-realms
+boxel doctor repair-realms
 ```
 
 ## Behavior
 
-`repair-realm` and `repair-realms` perform these repairs:
+`doctor repair-realm` and `doctor repair-realms` perform these repairs:
 - `.realm.json`: normalize `name`, `iconURL`, `backgroundURL`
 - `index.json`: ensure `relationships.cardsGrid.links.self` = `./cards-grid`
 - `cards-grid.json`: restore default cards-grid card if missing/corrupt

.claude/commands/setup.md

@@ -52,13 +52,13 @@ BOXEL_PASSWORD="password" npx boxel profile add -u @username:stack.cards -n "Sta
 
 ### 3. Verify
 ```bash
-npx boxel list
+npx boxel workspace-list
 ```
 
 ### 4. First Sync
-Help them sync a workspace:
+Help them pull a workspace (defaults to `~/boxel-workspaces/`):
 ```bash
-npx boxel sync @username/workspace ./workspace-name
+npx boxel pull https://app.boxel.ai/username/workspace/
 ```
 
 ## Profile Management
@@ -81,8 +81,8 @@ npx boxel profile migrate
 ## Success Message
 ```
 Setup complete! You can now:
-- `npx boxel list` - See your workspaces
-- `npx boxel sync @username/workspace` - Sync a workspace
+- `npx boxel workspace-list` - See your workspaces
+- `npx boxel pull <url>` - Pull a workspace to ~/boxel-workspaces/
 - `npx boxel watch .` - Monitor for changes
 - `npx boxel history .` - View/restore checkpoints
 

AGENTS.md

@@ -38,8 +38,8 @@ Trigger examples:
 - `sync`: bidirectional conflict resolution
 - `track`: local file watching with auto-checkpoints (use `--push` for real-time server sync)
 - `watch`: remote change watching (pulls server changes)
-- `repair-realm`: repair one realm metadata + starter cards + optional Matrix reconciliation
-- `repair-realms`: batch repair all owned realms and reconcile Matrix realm list
+- `doctor repair-realm`: repair one realm metadata + starter cards + optional Matrix reconciliation
+- `doctor repair-realms`: batch repair all owned realms and reconcile Matrix realm list
 
 After local edits tracked with `track`, push to server with:
 - `boxel sync . --prefer-local`
@@ -49,16 +49,16 @@ After local edits tracked with `track`, push to server with:
 If user has no profile configured:
 1. `npx boxel profile`
 2. `npx boxel profile add` (interactive preferred)
-3. `npx boxel list`
-4. First sync/pull into local workspace
+3. `npx boxel workspace-list`
+4. First sync/pull into local workspace (default root: `~/boxel-workspaces/`)
 
 Security note:
 - Prefer interactive password entry or `BOXEL_PASSWORD` env var.
 - Avoid plain `-p` password usage in shell history.
 
 ## Multi-Realm Guidance
-- Configure realms with `boxel realms --add ...`
-- Use `boxel realms --llm` for file-placement guidance.
+- Configure realms with `boxel realms add ...`
+- Use `boxel realms llm` for file-placement guidance.
 - Heuristic:
   - `.gts` -> code realm (`*.gts` pattern)
   - instances -> realm mapped for card type

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to `boxel-cli`. Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.0 — 2026-04-20
+
+Command-surface restructure plus the two regressions @backspace caught in his PR #15 review. Minor version bump because command names and default paths change in user-visible ways.
+
+### New
+
+- **`boxel doctor` parent command** groups maintenance tasks: `doctor repair-realm`, `doctor repair-realms`, `doctor consolidate-workspaces`, `doctor force-reindex`. Keeps the root command tree focused on day-to-day sync operations.
+- **`boxel workspace-list`** (formerly `boxel list`) lists Boxel workspaces the active profile can access. `boxel list` stays as a shorthand alias.
+- **`boxel realms <subcommand>`** — positional subcommands replace the old flag-based interface. `boxel realms add ./path`, `realms remove ./path`, `realms init`, `realms list`, `realms llm`. `boxel realms` with no args shows the list.
+- **Default workspace root at `~/boxel-workspaces/<domain>/<owner>/<realm>/`.** `boxel pull <url>` now works without a local-dir argument — it derives a canonical path from the URL and creates the directory. `doctor consolidate-workspaces` scans `~/boxel-workspaces/` by default.
+- Terminology discipline across docs and help text: **realm** = the server-side thing a URL points at; **workspace** = the Matrix-level organizational unit visible in the Boxel UI.
+
+### Fixed
+
+- **`--fix-index` was on by default, opposite of what PR #15 advertised.** Commander's `.option('--no-fix-index')` makes the underlying boolean default to `true`. Running `boxel doctor repair-realm <url>` silently rewrote `index.json` / `cards-grid.json` even on realms with customized index files (caught by @backspace on the Checkly-prerendered realm that lost its custom index). Flipped to `.option('--fix-index')` — now opt-in. Added regression tests that exercise commander parsing directly.
+- **Pull path extraction broke for published realms without an owner segment.** `https://realms-staging.stack.cards/boxel-homepage/` (1 segment) wrote to `.../boxel-homepage/boxel-homepage` (duplicated); `https://gabbro.staging.boxel.build/` (0 segments) wrote to `.../unknown-owner/workspace` (invented placeholders). The layout now adapts to the URL: 0 segments → `<host>/`, 1 segment → `<host>/<realm>/`, 2+ segments → `<host>/<owner>/<realm>/` (unchanged). `findManifestPaths()` walks 2-level layouts so legacy-path detection still works after the shape change.
+- **`track --push` showed "Push failed" with no detail on batch errors.** Now surfaces the underlying errors (e.g. `HTTP 413: Payload Too Large`) so you can tell a transient server problem from a size limit.
+- **`boxel realms remove <path>`** used to succeed silently on a path not in the config. Now errors with a clear "realm not found" message.
+- **Realm folder naming** now uses the full realm server hostname (no domain normalization). Prevents staging/production collisions when two realms share the owner/realm parts.
+
+### Changed (breaking)
+
+- **`boxel realms --add/--init/--remove/--llm` flag form removed.** PR #15 kept these as hidden aliases; per @backspace's review ("we might as well make a clean break as this is not officially released") they're gone. Use positional subcommands.
+- **`boxel doctor force-reindex`** replaces the top-level `touch` command semantics when used as a diagnostic; the plain `touch` command stays for everyday single-file re-indexing.
+
+### For contributors
+
+- New `test/commands/repair.test.ts` regression tests for commander flag parsing — catches the `--no-fix-index` default-inversion bug at the commander layer (the previous tests only checked the handler's `options.fixIndex ?? false` fallback, which ran after commander had already set the bad default).
+- New `test/lib/workspace-paths.test.ts` cases for 0-segment and 1-segment URLs.
+- Removed dead `realmsCommand()` legacy dispatcher and `RealmsOptions` interface from `src/commands/realms.ts`.
+
+---
+
 ## 1.0.2 — 2026-04-20
 
 Low-risk ports from `@cardstack/boxel-cli` (the official package in the Boxel monorepo). No user-visible command changes; architectural alignment + mild speedups.