fix(webapp): stop the CLI's AI help link dead-ending without an AI surface

Where neither Ask AI nor the agent can open, the redirect left `?aiHelp=` on the
environment page with nothing to read it. Send the question to the docs instead.

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/ask-ai-channels.test.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 import {
   agentDeepLinkParams,
+  aiHelpDocsUrl,
   aiHelpRedirectUrl,
   askAiCanOpen,
   askAiChannelTarget,
@@ -153,4 +154,21 @@ describe("wiring", () => {
   it("builds the CLI redirect through the shared helper", () => {
     expect(cliRoute).toContain("aiHelpRedirectUrl(");
   });
+
+  // Structural: the loader needs a session and a database, so the branch is asserted on source.
+  it("sends the CLI link to the docs when neither surface can open it", () => {
+    expect(cliRoute).toContain("if (!canOpenSomething)");
+    expect(cliRoute).toContain("redirect(aiHelpDocsUrl(query))");
+    expect(cliRoute).toContain("askAiCanOpen(");
+    expect(cliRoute).toContain("canAccessDashboardAgent(");
+  });
+});
+
+describe("aiHelpDocsUrl", () => {
+  it("carries the question to the docs", () => {
+    const url = new URL(aiHelpDocsUrl("Error: task timed out & failed"));
+
+    expect(url.origin + url.pathname).toBe("https://trigger.dev/docs");
+    expect(url.searchParams.get("q")).toBe("Error: task timed out & failed");
+  });
 });

apps/webapp/app/components/dashboard-agent/ask-ai-channels.ts

@@ -47,6 +47,16 @@ export function agentDeepLinkParams(availability: AskAiAvailability): readonly D
   return askAiChannelTarget(availability) === "ask-ai" ? NO_PARAMS : ASK_AI_PARAMS;
 }
 
+/**
+ * Where the same link lands when neither surface can open it: nothing in the dashboard would
+ * read the deep link, so the question goes to the docs rather than to a page that ignores it.
+ */
+export function aiHelpDocsUrl(query: string): string {
+  const docs = new URL("https://trigger.dev/docs");
+  docs.searchParams.set("q", query);
+  return docs.toString();
+}
+
 /**
  * Where `trigger dev`'s "Get a fix for this error using AI" link lands. Always on `origin`: an
  * absolute or protocol-relative `environmentPath` would otherwise decide the host itself, and

apps/webapp/app/routes/projects.$projectRef.ai-help.ts

@@ -1,17 +1,24 @@
 import { type LoaderFunctionArgs, redirect } from "@remix-run/server-runtime";
 import { z } from "zod";
-import { aiHelpRedirectUrl } from "~/components/dashboard-agent/ask-ai-channels";
+import {
+  aiHelpDocsUrl,
+  aiHelpRedirectUrl,
+  askAiCanOpen,
+} from "~/components/dashboard-agent/ask-ai-channels";
 import { prisma } from "~/db.server";
 import { env } from "~/env.server";
-import { requireUserId } from "~/services/session.server";
+import { featuresForRequest } from "~/features.server";
+import { hasAdminDisplayAccess, requireUser } from "~/services/session.server";
+import { canAccessDashboardAgent } from "~/v3/canAccessDashboardAgent.server";
 import { v3EnvironmentPath } from "~/utils/pathBuilder";
 
 const ParamsSchema = z.object({
   projectRef: z.string(),
 });
 
 export async function loader({ params, request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
+  const user = await requireUser(request);
+  const userId = user.id;
 
   const validatedParams = ParamsSchema.parse(params);
 
@@ -42,6 +49,24 @@ export async function loader({ params, request }: LoaderFunctionArgs) {
     return new Response("No query", { status: 404 });
   }
 
+  const showAdminUi = hasAdminDisplayAccess(user);
+  const canOpenSomething =
+    askAiCanOpen({
+      isManagedCloud: featuresForRequest(request).isManagedCloud,
+      kapaWebsiteId: env.KAPA_AI_WEBSITE_ID,
+    }) ||
+    (await canAccessDashboardAgent({
+      userId,
+      isAdmin: showAdminUi && user.admin,
+      isImpersonating: showAdminUi && user.isImpersonating,
+      organizationSlug: project.organization.slug,
+      orgFeatureFlags: (project.organization.featureFlags as Record<string, unknown>) ?? {},
+    }));
+
+  if (!canOpenSomething) {
+    return redirect(aiHelpDocsUrl(query));
+  }
+
   return redirect(
     aiHelpRedirectUrl({
       environmentPath: v3EnvironmentPath(