feat(webapp): dashboard agent — UI (#4529)

Stacked on #4418. Merge that first.

The UI slice of the dashboard agent: the side panel, the chat transport
wiring, message and card rendering, suggested prompts, and chat history.
#4418 works without this — the system is simply invisible. The diff is
mostly components, so the notes below cover only the three decisions you
can't read off the markup. Behavior and a hands-on walkthrough live in
GUIDEBOOK.md, which lands with #4525.

## Decisions worth knowing

- **Action rows always render at the end of a turn.** The model's
emission order isn't trusted for layout, so action blocks are split out
of the stream and appended last. Display only — `answered` stays keyed
on the emission index.
- **The last-chat memory is org-true.** It's keyed by the chat's own
organization, and a foreign or deleted chat comes back as a 404 the
client treats as gone, rather than an empty chat it keeps around.
- **A dead stream self-heals from the settled transcript.** Terminal
records are written to the chat row after the client's stream closes, so
the panel re-reads it. The poll gate is any unfinished turn — a dangling
tool part, not just an open investigation.

## Notes

- Gated by `canAccessDashboardAgent`; no behavior change with the flag
off.
- Page marks: `handle.agentPageContext` on 47 routes, ~20 lines each.
- Entry points: Ask Trigger button, ⌘J, Help & Feedback. The old ⌘I and
`?aiHelp=` links keep working.

## Screenshots

<img width="1440" height="788" alt="Screenshot 2026-08-07 at 15 14 29"
src="https://github.com/user-attachments/assets/f4e89e8d-13ed-4be3-a88d-d5cca3ece0fa"
/>

Author: kathiekiwi

.changeset/chat-stream-mid-turn-reconnect.md

@@ -4,4 +4,4 @@
 "trigger.dev": patch
 ---
 
-Chat in the browser now reconnects when the connection drops mid-turn, instead of leaving the reply stuck as if it were still generating. Reports can be fetched as structured data with the `json` format, and the shortest report period is now one minute (`30m`, `1h`, `7d`). The `mint-token` command's help is clearer too: a token minted without `--cap` is read-only, and `--ttl` shows the correct maximum lifetime of 7 days.
+Chat in the browser now reconnects when the connection drops mid-turn, instead of leaving the reply stuck as if it were still generating. Reports can be fetched as structured data with the `json` format, and the shortest report period is now one minute (`1m`, `30m`, `1h`, `7d`). The `mint-token` command's help is clearer too: a token minted without `--cap` is read-only, and `--ttl` shows the correct maximum lifetime of 7 days.

.claude/agents/code-reviewer.md

@@ -0,0 +1,13 @@
+---
+name: code-reviewer
+description: Adversarially verifies one landed packet against its requirement; read-only.
+model: opus
+---
+
+You are an adversarial code reviewer for one landed packet. READ-ONLY: never modify code, never commit, never push, never post to GitHub.
+
+- Try to refute that the change answers its stated requirement; look for the failure scenario, not confirmation.
+- Check the diff for unrelated drift, dead code, broken semantics of neighbors, and whether tests prove the actual invariant (would the test fail if the fix were subtly wrong?).
+- Check the change landed in the correct PR/branch of the stack.
+- Distinguish fact from inference; cite exact file:line evidence.
+- Return: verdict (approve / needs-changes) with evidence per concern, and the exact minimal correction when needs-changes.

.claude/agents/code-writer.md

@@ -0,0 +1,16 @@
+---
+name: code-writer
+description: Implements exactly one work packet — minimal diff, targeted checks, own-paths-only commits.
+model: opus
+---
+
+You are a code writer. Implement exactly the one work packet in your prompt.
+
+- Minimal diff; match surrounding style and idiom.
+- Prefer no comment at all; comment only a non-obvious constraint, max 2 short lines. All texts (comments, commit messages) short, clear, simple.
+- Verify the packet's own diagnosis against the code before applying; if it is wrong, STOP without committing and report why.
+- Run only the targeted checks for your packet: the relevant vitest files, `pnpm run typecheck --filter <pkg>` when the change warrants it. Never full suites unless asked.
+- `pnpm run format` on touched files before committing.
+- Stage and commit ONLY your packet's files. Conventional commit message. NO Claude attribution, no Co-Authored-By.
+- Push only if the packet explicitly says to.
+- Return: what changed, evidence (test output), commit SHA, and anything contradicting the diagnosis.

.claude/agents/software-architect.md

@@ -0,0 +1,12 @@
+---
+name: software-architect
+description: Resolves contested design questions against the specs; decision + rationale, never code.
+model: opus
+---
+
+You are a software architect. Resolve exactly the contested design question in your prompt against the given specs/contracts. READ-ONLY.
+
+- Ground the decision in the actual code and the project's design contracts (GUIDEBOOK, Linear specs) — not in generic best practice.
+- Weigh stack boundaries: which PR owns the change, what merges independently.
+- Prefer the smallest decision that unblocks the packet; flag speculative architecture rather than endorsing it.
+- Return: the decision, its rationale, rejected alternatives (one line each), and exactly what the dependent packet should do.

apps/webapp/app/components/AskAI.tsx

@@ -1,7 +1,7 @@
 /**
- * @deprecated Superseded by the dashboard agent (`components/dashboard-agent`). Nothing mounts
- * this any more — every Ask AI entry point now opens Ask Trigger. Kept until the agent has
- * shipped, then removed along with `@kapaai/react-sdk` and `KAPA_AI_WEBSITE_ID`.
+ * Mostly superseded by the dashboard agent (`components/dashboard-agent`), which owns every
+ * entry point except two: ⌘I and the CLI's `?aiHelp=` link still open Ask AI. `AskAIRoot` is
+ * mounted by the `_app` layout for those; the `AskAI` button below is mounted nowhere.
  */
 
 import {
@@ -17,13 +17,17 @@ import { useSearchParams } from "@remix-run/react";
 import DOMPurify from "dompurify";
 import { motion } from "framer-motion";
 import { marked } from "marked";
-import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
-import { useTypedRouteLoaderData } from "remix-typedjson";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { AISparkleIcon } from "~/assets/icons/AISparkleIcon";
 import { SparkleListIcon } from "~/assets/icons/SparkleListIcon";
-import { useFeatures } from "~/hooks/useFeatures";
+import { useAskAiAvailability } from "~/hooks/useAskAiAvailability";
 import { useShortcutKeys } from "~/hooks/useShortcutKeys";
-import { type loader } from "~/root";
+import {
+  ASK_AI_DEEP_LINK_PARAM,
+  ASK_AI_SHORTCUT,
+  askAiCanOpen,
+} from "./dashboard-agent/ask-ai-channels";
+import { useAskAiHost } from "./dashboard-agent/askAiOpenRequest";
 import { Button } from "./primitives/Buttons";
 import { Callout } from "./primitives/Callout";
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from "./primitives/Dialog";
@@ -40,11 +44,6 @@ import {
 } from "./primitives/Tooltip";
 import { ClientOnly } from "remix-utils/client-only";
 
-function useKapaWebsiteId() {
-  const routeMatch = useTypedRouteLoaderData<typeof loader>("root");
-  return routeMatch?.kapa.websiteId;
-}
-
 /** Open/close state for the Ask AI dialog, including the `?aiHelp=` deep-link handling. */
 function useAskAIState() {
   const [isOpen, setIsOpen] = useState(false);
@@ -67,14 +66,14 @@ function useAskAIState() {
 
   // Handle URL param functionality
   useEffect(() => {
-    const aiHelp = searchParams.get("aiHelp");
+    const aiHelp = searchParams.get(ASK_AI_DEEP_LINK_PARAM);
     if (aiHelp) {
       // Delay to avoid hCaptcha bot detection
       window.setTimeout(() => openAskAI(aiHelp), 1000);
 
       // Clone instead of mutating in place
       const next = new URLSearchParams(searchParams);
-      next.delete("aiHelp");
+      next.delete(ASK_AI_DEEP_LINK_PARAM);
       setSearchParams(next);
     }
   }, [searchParams, openAskAI]);
@@ -83,45 +82,30 @@ function useAskAIState() {
 }
 
 /**
- * Hosts Ask AI (Kapa provider, ⌘I shortcut, dialog) for a menu that renders its own trigger. Wrap
- * it around the popover, not inside, so the dialog and shortcut survive the popover closing.
- * `children` receives the open function, or undefined when Ask AI is unavailable (self-hosted, no
- * Kapa website id, or SSR).
- *
- * @deprecated See the note at the top of this file.
+ * Hosts Ask AI (Kapa provider, ⌘I shortcut, dialog). It renders no page content and wraps
+ * nothing: entry points reach it through `requestAskAi`, so the Kapa provider mounting after
+ * hydration can never remount the app around it.
  */
-export function AskAIRoot({
-  children,
-}: {
-  children: (openAskAI: (() => void) | undefined) => ReactNode;
-}) {
-  const { isManagedCloud } = useFeatures();
-  const websiteId = useKapaWebsiteId();
+export function AskAIRoot() {
+  const availability = useAskAiAvailability();
 
-  if (!isManagedCloud || !websiteId) {
-    return <>{children(undefined)}</>;
+  if (!askAiCanOpen(availability)) {
+    return null;
   }
 
-  return (
-    <ClientOnly fallback={<>{children(undefined)}</>}>
-      {() => <AskAIRootProvider websiteId={websiteId}>{children}</AskAIRootProvider>}
-    </ClientOnly>
-  );
+  const websiteId = availability.kapaWebsiteId!;
+
+  return <ClientOnly>{() => <AskAIRootProvider websiteId={websiteId} />}</ClientOnly>;
 }
 
-function AskAIRootProvider({
-  websiteId,
-  children,
-}: {
-  websiteId: string;
-  children: (openAskAI: () => void) => ReactNode;
-}) {
+function AskAIRootProvider({ websiteId }: { websiteId: string }) {
   const { isOpen, setIsOpen, initialQuery, openAskAI, closeAskAI } = useAskAIState();
 
   useShortcutKeys({
-    shortcut: { modifiers: ["mod"], key: "i", enabledOnInputElements: true },
+    shortcut: ASK_AI_SHORTCUT,
     action: () => openAskAI(),
   });
+  useAskAiHost(openAskAI);
 
   return (
     <KapaProvider
@@ -134,7 +118,6 @@ function AskAIRootProvider({
       }}
       botProtectionMechanism="hcaptcha"
     >
-      {children(() => openAskAI())}
       <AskAIDialog
         initialQuery={initialQuery}
         isOpen={isOpen}
@@ -145,15 +128,16 @@ function AskAIRootProvider({
   );
 }
 
-/** @deprecated See the note at the top of this file. */
+/** @deprecated Mounted nowhere: the sidebar's AI entry point is the dashboard agent. */
 export function AskAI({ isCollapsed = false }: { isCollapsed?: boolean }) {
-  const { isManagedCloud } = useFeatures();
-  const websiteId = useKapaWebsiteId();
+  const availability = useAskAiAvailability();
 
-  if (!isManagedCloud || !websiteId) {
+  if (!askAiCanOpen(availability)) {
     return null;
   }
 
+  const websiteId = availability.kapaWebsiteId!;
+
   return (
     <ClientOnly
       fallback={

apps/webapp/app/components/BlankStatePanels.tsx

@@ -35,7 +35,7 @@ import {
   v3NewProjectAlertPath,
   v3NewSchedulePath,
 } from "~/utils/pathBuilder";
-import { AskAI } from "./AskAI";
+import { AskAgentButton } from "./dashboard-agent/AskAgentButton";
 import { CodeBlock } from "./code/CodeBlock";
 import { useDevPresence } from "./DevPresence";
 import { InlineCode } from "./code/InlineCode";
@@ -65,6 +65,55 @@ import {
 import { StepContentContainer } from "./StepContentContainer";
 import { V4Badge } from "./V4Badge";
 
+/**
+ * What the agent is asked when it's opened from a deployment setup panel. The panel is the docs
+ * answer; the agent is for the part the docs can't answer — this project, this environment.
+ */
+const ASK_AGENT_DEPLOY_PROMPT =
+  "I'm trying to deploy my tasks to this environment. Walk me through it and tell me if anything about this project or environment is going to get in the way.";
+
+/** The docs links the deployment panels offer to anyone without the agent. */
+function DeployDocsLinks() {
+  return (
+    <>
+      <SimpleTooltip
+        asChild
+        tabbable
+        button={
+          // Span wrapper: LinkButton drops the pointer-event props Radix injects via asChild, so
+          // the tooltip trigger has to be a plain element (same pattern as FavoritePageButton).
+          <span className="flex">
+            <LinkButton
+              variant="small-menu-item"
+              LeadingIcon={BookOpenIcon}
+              leadingIconClassName="text-blue-500"
+              to={docsPath("deployment/overview")}
+              aria-label="Deploy docs"
+            />
+          </span>
+        }
+        content="Deploy docs"
+      />
+      <SimpleTooltip
+        asChild
+        tabbable
+        button={
+          <span className="flex">
+            <LinkButton
+              variant="small-menu-item"
+              LeadingIcon={QuestionMarkCircleIcon}
+              leadingIconClassName="text-blue-500"
+              to={docsPath("troubleshooting#deployment")}
+              aria-label="Troubleshooting docs"
+            />
+          </span>
+        }
+        content="Troubleshooting docs"
+      />
+    </>
+  );
+}
+
 export function HasNoTasksDev({ initializedAt }: { initializedAt: Date | string | null }) {
   const { isConnected } = useDevPresence();
   const initialized = !!initializedAt;
@@ -330,29 +379,10 @@ export function DeploymentsNoneDev() {
           <Header1>Deploy your tasks</Header1>
         </div>
         <div className="flex items-center">
-          <SimpleTooltip
-            button={
-              <LinkButton
-                variant="small-menu-item"
-                LeadingIcon={BookOpenIcon}
-                leadingIconClassName="text-blue-500"
-                to={docsPath("deployment/overview")}
-              />
-            }
-            content="Deploy docs"
-          />
-          <SimpleTooltip
-            button={
-              <LinkButton
-                variant="small-menu-item"
-                LeadingIcon={QuestionMarkCircleIcon}
-                leadingIconClassName="text-blue-500"
-                to={docsPath("troubleshooting#deployment")}
-              />
-            }
-            content="Troubleshooting docs"
-          />
-          <AskAI />
+          {/* One entry point instead of two: the docs links were a guess at which page you
+              needed, and the agent can look at this project and answer for it. Someone with no
+              agent still gets the links. */}
+          <AskAgentButton prompt={ASK_AGENT_DEPLOY_PROMPT} fallback={<DeployDocsLinks />} />
         </div>
       </div>
       <StepNumber stepNumber="→" title="Switch to a deployed environment" />
@@ -718,29 +748,10 @@ function DeploymentOnboardingSteps() {
           </Header1>
         </div>
         <div className="flex items-center">
-          <SimpleTooltip
-            button={
-              <LinkButton
-                variant="small-menu-item"
-                LeadingIcon={BookOpenIcon}
-                leadingIconClassName="text-blue-500"
-                to={docsPath("deployment/overview")}
-              />
-            }
-            content="Deploy docs"
-          />
-          <SimpleTooltip
-            button={
-              <LinkButton
-                variant="small-menu-item"
-                LeadingIcon={QuestionMarkCircleIcon}
-                leadingIconClassName="text-blue-500"
-                to={docsPath("troubleshooting#deployment")}
-              />
-            }
-            content="Troubleshooting docs"
-          />
-          <AskAI />
+          {/* One entry point instead of two: the docs links were a guess at which page you
+              needed, and the agent can look at this project and answer for it. Someone with no
+              agent still gets the links. */}
+          <AskAgentButton prompt={ASK_AGENT_DEPLOY_PROMPT} fallback={<DeployDocsLinks />} />
         </div>
       </div>
       <ClientTabs defaultValue="github">