===================================================================
--- a/actions/navigate.ts
+++ b/actions/navigate.ts
@@ -1,25 +1,39 @@
-import { defineAction } from "@agent-native/core/action";
+/**
+ * Navigate the UI to a view.
+ *
+ * Writes a navigate command to application state which the UI reads and auto-deletes.
+ *
+ * Usage:
+ *   pnpm action navigate --view=home
+ *   pnpm action navigate --path=/some/route
+ *
+ * Options:
+ *   --view   View name to navigate to
+ *   --path   URL path to navigate to
+ */
+
+import { defineAction, fail } from "@agent-native/core/action";
 import { writeAppStateForCurrentTab } from "@agent-native/core/application-state";
 import { z } from "zod";
 
 export default defineAction({
   description:
-    "Navigate the UI to a specific view or path. Writes a navigate command to application state which the UI reads and auto-deletes.",
+    "Navigate the UI to a specific view or path. Writes a navigate command to application state which the UI reads and auto-deletes. The default product surface is the home canvas at /; agent chat stays in the right rail.",
   schema: z.object({
     view: z.string().optional().describe("View name to navigate to"),
     path: z.string().optional().describe("URL path to navigate to"),
-    threadId: z.string().optional().describe("Chat thread ID to open"),
   }),
   http: false,
   run: async (args) => {
     if (!args.view && !args.path) {
-      throw new Error("At least --view or --path is required.");
+      fail("At least --view or --path is required.", {
+        errorCode: "navigate_target_required",
+      });
     }
     const nav: Record<string, string> = {};
     if (args.view) nav.view = args.view;
     if (args.path) nav.path = args.path;
-    if (args.threadId) nav.threadId = args.threadId;
     nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     await writeAppStateForCurrentTab("navigate", nav);
     return `Navigating to ${args.view || args.path}`;
   },