Update workspace tooling and query planning

Author: rowantrollope

AGENTS.md

@@ -232,3 +232,6 @@ The most important implementation seams are:
   behavior, check for duplicate Vite listeners from sibling worktrees.
   `localhost` can hit an IPv6 listener from another checkout while
   `127.0.0.1` hits the current repo.
+- Control-plane import/checkpoint JSON fields typed as `map[string][]byte`
+  expect base64-encoded string values. Small synthetic manifests can avoid that
+  by using `ManifestEntry.inline`, which is already base64 text.

cmd/afs/afs_surface_test.go

@@ -25,10 +25,14 @@ func TestConfigPathDefaultsToAFSConfig(t *testing.T) {
 	}
 }
 
-func TestWorkspaceRootShortcutsAreHiddenAliases(t *testing.T) {
+func TestWorkspaceRootShortcutsAreDocumentedAliases(t *testing.T) {
 	t.Helper()
 
-	for _, command := range []string{"mount", "unmount", "create", "list", "info", "import", "fork", "delete"} {
+	for _, command := range []string{
+		"mount", "unmount", "create", "list", "clone", "default",
+		"set-default", "unset-default", "info", "import", "fork",
+		"versioning", "delete",
+	} {
 		if !isWorkspaceRootShortcut(command) {
 			t.Fatalf("isWorkspaceRootShortcut(%q) = false, want true", command)
 		}
@@ -46,11 +50,18 @@ func TestWorkspaceRootShortcutsAreHiddenAliases(t *testing.T) {
 	}
 
 	out := captureStderrText(t, printUsage)
-	for _, hidden := range []string{"  mount", "  unmount", "  create", "  list", "  import", "  fork", "  delete", "  reset"} {
-		if strings.Contains(out, hidden) {
-			t.Fatalf("top-level help should not document hidden shortcut %q:\n%s", hidden, out)
+	for _, documented := range []string{
+		"Workspace Shortcuts", "mount", "unmount", "create", "list", "clone",
+		"default", "set-default", "unset-default", "info", "import", "fork",
+		"versioning", "delete",
+	} {
+		if !strings.Contains(out, documented) {
+			t.Fatalf("top-level help should document workspace shortcut %q:\n%s", documented, out)
 		}
 	}
+	if strings.Contains(out, "  reset") {
+		t.Fatalf("top-level help should not document non-workspace shortcut %q:\n%s", "reset", out)
+	}
 }
 
 func TestCompactDisplayPathUsesParentAndFilename(t *testing.T) {

cmd/afs/main.go

@@ -107,7 +107,9 @@ func main() {
 
 func isWorkspaceRootShortcut(command string) bool {
 	switch command {
-	case "mount", "unmount", "create", "list", "info", "import", "fork", "delete":
+	case "mount", "unmount", "create", "list", "clone", "default",
+		"set-default", "unset-default", "info", "import", "fork",
+		"versioning", "delete":
 		return true
 	default:
 		return false
@@ -140,7 +142,7 @@ func printUsage() {
 	fmt.Fprintf(w, "%sCommands:%s\n", bold, reset)
 	fmt.Fprintf(w, "  %sstatus%s             %sshow AFS status and local workspace mounts%s\n\n", bold, reset, dim, reset)
 
-	fmt.Fprintf(w, "  %sws%s (workspace)     %smount, unmount, create, list, import, fork, versioning, delete%s\n", bold, reset, dim, reset)
+	fmt.Fprintf(w, "  %sws%s (workspace)     %smount, create, list, clone, defaults, import, fork, versioning%s\n", bold, reset, dim, reset)
 	fmt.Fprintf(w, "  %sfs%s (filesystem)    %sread, search, and safely write workspace files%s\n", bold, reset, dim, reset)
 	fmt.Fprintf(w, "  %scp%s (checkpoint)    %screate, list, show, diff, restore%s\n", bold, reset, dim, reset)
 	fmt.Fprintf(w, "  %slog%s                %sWorkspace file-change log%s\n\n", bold, reset, dim, reset)
@@ -151,15 +153,20 @@ func printUsage() {
 	fmt.Fprintf(w, "  %sdatabase%s           %sadvanced database operations%s\n", bold, reset, dim, reset)
 	fmt.Fprintf(w, "  %smcp%s                %sstart the MCP server%s\n\n", bold, reset, dim, reset)
 
+	fmt.Fprintf(w, "%sWorkspace Shortcuts:%s\n", bold, reset)
+	fmt.Fprintf(w, "  %sOmit \"ws\" for:%s mount, unmount, create, list, clone, default, set-default,\n", dim, reset)
+	fmt.Fprintf(w, "                 unset-default, info, import, fork, versioning, delete\n")
+	fmt.Fprintf(w, "  %sExample:%s %s%s mount demo ~/demo%s  %s(same as %s ws mount demo ~/demo)%s\n\n", dim, reset, orange, bin, reset, dim, bin, reset)
+
 	fmt.Fprintf(w, "%sExamples:%s\n", bold, reset)
 	fmt.Fprintf(w, "  %s%s auth login%s\n    Sign in to AFS Cloud via browser.\n", orange, bin, reset)
-	fmt.Fprintf(w, "  %s%s ws mount getting-started ~/getting-started%s\n    Mount a workspace to a local folder.\n", orange, bin, reset)
-	fmt.Fprintf(w, "  %s%s ws unmount getting-started%s\n    Stop managing that workspace; keep local files.\n\n", orange, bin, reset)
+	fmt.Fprintf(w, "  %s%s mount getting-started ~/getting-started%s\n    Mount a workspace to a local folder.\n", orange, bin, reset)
+	fmt.Fprintf(w, "  %s%s unmount getting-started%s\n    Stop managing that workspace; keep local files.\n\n", orange, bin, reset)
 
 	fmt.Fprintf(w, "%sCommon Flows:%s\n", bold, reset)
-	fmt.Fprintf(w, "  %sFresh setup:%s %s%s auth login%s → %s%s ws mount getting-started ~/getting-started%s\n", dim, reset, orange, bin, reset, orange, bin, reset)
-	fmt.Fprintf(w, "  %sNew workspace:%s %s%s ws create demo%s → %s%s ws mount demo ~/demo%s\n", dim, reset, orange, bin, reset, orange, bin, reset)
-	fmt.Fprintf(w, "  %sImport existing files:%s %s%s ws import --mount-at-source demo ~/src/demo%s\n\n", dim, reset, orange, bin, reset)
+	fmt.Fprintf(w, "  %sFresh setup:%s %s%s auth login%s → %s%s mount getting-started ~/getting-started%s\n", dim, reset, orange, bin, reset, orange, bin, reset)
+	fmt.Fprintf(w, "  %sNew workspace:%s %s%s create demo%s → %s%s mount demo ~/demo%s\n", dim, reset, orange, bin, reset, orange, bin, reset)
+	fmt.Fprintf(w, "  %sImport existing files:%s %s%s import --mount-at-source demo ~/src/demo%s\n\n", dim, reset, orange, bin, reset)
 
 	fmt.Fprintf(w, "%sConfig:%s %s%s%s\n", bold, reset, dim, compactDisplayPath(configPath()), reset)
 }