feat(webapp,cli,database): track real dev onboarding progress

The dev environment "Get set up" panel now reflects actual progress instead of static instructions. Running trigger init records the project as initialized (via a new project-scoped endpoint the CLI calls), so step 1 ticks off, and the panel updates live as the dev server connects and tasks register. Adds a "Copy AI agent prompt" button that copies a ready-to-paste setup prompt pre-filled with the project reference, and updates the init scaffold to import from @trigger.dev/sdk instead of the deprecated /v3 subpath.

Author: ericallam

.changeset/dev-onboarding-progress.md

@@ -0,0 +1,7 @@
+---
+"trigger.dev": patch
+---
+
+The dev environment onboarding now tracks real progress. After you run `init`, the setup checklist marks your project as initialized, and it updates live as your dev server connects and your tasks register. The blank state also adds a "Copy AI agent prompt" button that copies a ready-to-paste setup prompt (pre-filled with your project reference) for Claude Code, Cursor, or any coding agent.
+
+The `init` scaffold now imports from `@trigger.dev/sdk` instead of the deprecated `@trigger.dev/sdk/v3` subpath.

apps/webapp/app/components/BlankStatePanels.tsx

@@ -8,6 +8,7 @@ import {
   QuestionMarkCircleIcon,
   RectangleGroupIcon,
   RectangleStackIcon,
+  SparklesIcon,
   Squares2X2Icon,
 } from "@heroicons/react/20/solid";
 import { useLocation } from "react-use";
@@ -36,6 +37,7 @@ import {
 } from "~/utils/pathBuilder";
 import { AskAI } from "./AskAI";
 import { CodeBlock } from "./code/CodeBlock";
+import { useDevPresence } from "./DevPresence";
 import { InlineCode } from "./code/InlineCode";
 import { environmentFullTitle, EnvironmentIcon } from "./environments/EnvironmentLabel";
 import { Feedback } from "./Feedback";
@@ -54,6 +56,7 @@ import { StepNumber } from "./primitives/StepNumber";
 import { TextLink } from "./primitives/TextLink";
 import { SimpleTooltip } from "./primitives/Tooltip";
 import {
+  InitAgentPromptV3,
   InitCommandV3,
   PackageManagerProvider,
   TriggerDeployStep,
@@ -63,11 +66,16 @@ import { StepContentContainer } from "./StepContentContainer";
 import { V4Badge } from "./V4Badge";
 
 export function HasNoTasksDev() {
+  const project = useProject();
+  const { isConnected } = useDevPresence();
+  const initialized = !!project.initializedAt;
+  const devConnected = isConnected === true;
+
   return (
     <PackageManagerProvider>
       <div>
         <div className="mb-6 flex items-center justify-between border-b">
-          <Header1 spacing>Get setup in 3 minutes</Header1>
+          <Header1 spacing>Get set up in 2 minutes</Header1>
           <div className="flex items-center gap-2">
             <Feedback
               button={
@@ -79,22 +87,75 @@ export function HasNoTasksDev() {
             />
           </div>
         </div>
-        <StepNumber stepNumber="1" title="Run the CLI 'init' command in an existing project" />
-        <StepContentContainer>
-          <InitCommandV3 />
-          <Paragraph spacing>
-            You'll notice a new folder in your project called{" "}
-            <InlineCode variant="small">trigger</InlineCode>. We've added a few simple example tasks
-            in there to help you get started.
-          </Paragraph>
-        </StepContentContainer>
-        <StepNumber stepNumber="2" title="Run the CLI 'dev' command" />
+        {!initialized && (
+          <>
+            <div className="flex flex-col gap-4 rounded-md border border-indigo-400/20 bg-indigo-800/10 p-4 sm:flex-row sm:items-center">
+              <span className="flex size-9 shrink-0 items-center justify-center rounded-md bg-indigo-500/15 text-indigo-400">
+                <SparklesIcon className="size-5" />
+              </span>
+              <div className="min-w-0 flex-1">
+                <Paragraph className="text-text-bright">Set it up with your AI agent</Paragraph>
+                <Paragraph variant="small" className="text-text-dimmed">
+                  Copy a ready-to-paste prompt for Claude Code, Cursor, or any coding agent. It
+                  includes your project reference.
+                </Paragraph>
+              </div>
+              <div className="shrink-0">
+                <InitAgentPromptV3 />
+              </div>
+            </div>
+            <div className="my-6 flex items-center gap-3">
+              <div className="h-px flex-1 bg-grid-bright" />
+              <span className="text-xs uppercase tracking-wide text-text-dimmed">
+                or set it up yourself
+              </span>
+              <div className="h-px flex-1 bg-grid-bright" />
+            </div>
+          </>
+        )}
+        <StepNumber
+          stepNumber="1"
+          title={initialized ? "Project initialized" : "Initialize your project"}
+          complete={initialized}
+        />
         <StepContentContainer>
-          <TriggerDevStepV3 />
+          {initialized ? (
+            <Paragraph>
+              Your project is initialized. Your tasks live in the{" "}
+              <InlineCode variant="small">trigger</InlineCode> directory.
+            </Paragraph>
+          ) : (
+            <>
+              <InitCommandV3 />
+              <Paragraph spacing>
+                Run this in an existing project. You'll notice a new folder called{" "}
+                <InlineCode variant="small">trigger</InlineCode> with a few example tasks to help
+                you get started.
+              </Paragraph>
+            </>
+          )}
         </StepContentContainer>
-        <StepNumber stepNumber="3" title="Waiting for tasks" displaySpinner />
+        <StepNumber
+          stepNumber="2"
+          title={devConnected ? "Dev server connected" : "Start the dev server"}
+          complete={devConnected}
+          displaySpinner={!devConnected}
+        />
         <StepContentContainer>
-          <Paragraph>This page will automatically refresh.</Paragraph>
+          {devConnected ? (
+            <Paragraph>
+              Your dev server is connected. Your tasks will appear here automatically as soon as
+              they register.
+            </Paragraph>
+          ) : (
+            <>
+              <TriggerDevStepV3 />
+              <Paragraph spacing>
+                Keep this running while you develop. Once your tasks register, this page updates
+                automatically.
+              </Paragraph>
+            </>
+          )}
         </StepContentContainer>
       </div>
     </PackageManagerProvider>

apps/webapp/app/components/SetupCommands.tsx

@@ -1,7 +1,9 @@
-import { createContext, useContext, useState } from "react";
+import { CheckIcon, SparklesIcon } from "@heroicons/react/20/solid";
+import { createContext, useContext, useRef, useState } from "react";
 import { useAppOrigin } from "~/hooks/useAppOrigin";
 import { useProject } from "~/hooks/useProject";
 import { useTriggerCliTag } from "~/hooks/useTriggerCliTag";
+import { Button } from "./primitives/Buttons";
 import {
   ClientTabs,
   ClientTabsContent,
@@ -10,6 +12,7 @@ import {
 } from "./primitives/ClientTabs";
 import { ClipboardField } from "./primitives/ClipboardField";
 import { Header3 } from "./primitives/Headers";
+import { SimpleTooltip } from "./primitives/Tooltip";
 
 type PackageManagerContextType = {
   activePackageManager: string;
@@ -36,26 +39,23 @@ function usePackageManager() {
   return context;
 }
 
-function getApiUrlArg() {
+function useApiUrl() {
   const appOrigin = useAppOrigin();
 
-  let apiUrl: string | undefined = undefined;
-
   switch (appOrigin) {
     case "https://cloud.trigger.dev":
-      // don't display the arg, use the CLI default
-      break;
+      return undefined;
     case "https://test-cloud.trigger.dev":
-      apiUrl = "https://test-api.trigger.dev";
-      break;
+      return "https://test-api.trigger.dev";
     case "https://internal.trigger.dev":
-      apiUrl = "https://internal-api.trigger.dev";
-      break;
+      return "https://internal-api.trigger.dev";
     default:
-      apiUrl = appOrigin;
-      break;
+      return appOrigin;
   }
+}
 
+function getApiUrlArg() {
+  const apiUrl = useApiUrl();
   return apiUrl ? `-a ${apiUrl}` : undefined;
 }
 
@@ -117,6 +117,86 @@ export function InitCommandV3({ title }: TabsProps) {
   );
 }
 
+function buildAgentSetupPrompt({
+  projectRef,
+  apiUrl,
+  cliTag,
+}: {
+  projectRef: string;
+  apiUrl: string | undefined;
+  cliTag: string;
+}) {
+  const apiUrlArg = apiUrl ? ` -a ${apiUrl}` : "";
+  const apiUrlLine = apiUrl ? `\nTrigger.dev API URL: ${apiUrl}` : "";
+
+  return `Set up Trigger.dev in this project.
+
+Trigger.dev runs your background tasks. This is an existing codebase — add Trigger.dev to it and get one task running in the development environment.
+
+Project reference: ${projectRef}${apiUrlLine}
+
+How to do it:
+1. If you have the Trigger.dev MCP server available, use its "initialize_project" tool with the project reference above.
+2. Otherwise run this and follow its output:
+   npx trigger.dev@${cliTag} init -p ${projectRef}${apiUrlArg}
+3. If you set it up by hand, follow https://trigger.dev/docs/manual-setup and make sure you end up with:
+   - "@trigger.dev/sdk" installed (latest) and "@trigger.dev/build" as a dev dependency
+   - a trigger.config.ts with: import { defineConfig } from "@trigger.dev/sdk", project: "${projectRef}", dirs: ["./src/trigger"], and a maxDuration
+   - a src/trigger/ directory with at least one exported task created with task() from "@trigger.dev/sdk"
+   - trigger.config.ts added to tsconfig "include", and ".trigger" added to .gitignore
+
+Golden rules:
+- Import from "@trigger.dev/sdk". Never "@trigger.dev/sdk/v3" or the deprecated client.defineJob.
+- Export every task, including subtasks.
+- Use the built-in fetch, not node-fetch.
+- Never wrap wait.*, triggerAndWait, or batchTriggerAndWait in Promise.all.
+
+Two steps I have to do myself — ask me when you need them:
+- Running "npx trigger.dev@${cliTag} login" (it opens a browser).
+- Giving you the development TRIGGER_SECRET_KEY from the dashboard to put in .env.
+
+When you're done, run "npx trigger.dev@${cliTag} dev" and confirm the task shows up in the Trigger.dev dashboard.`;
+}
+
+export function InitAgentPromptV3() {
+  const project = useProject();
+  const apiUrl = useApiUrl();
+  const cliTag = useTriggerCliTag();
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const onCopy = () => {
+    const prompt = buildAgentSetupPrompt({
+      projectRef: project.externalRef,
+      apiUrl,
+      cliTag,
+    });
+    setCopied(true);
+    if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    timeoutRef.current = setTimeout(() => setCopied(false), 2000);
+    void navigator.clipboard.writeText(prompt).catch(() => {});
+  };
+
+  return (
+    <SimpleTooltip
+      asChild
+      tabbable
+      button={
+        <Button
+          type="button"
+          variant="primary/medium"
+          LeadingIcon={copied ? CheckIcon : SparklesIcon}
+          leadingIconClassName={copied ? "text-success" : undefined}
+          onClick={onCopy}
+        >
+          {copied ? "Copied prompt" : "Copy AI agent prompt"}
+        </Button>
+      }
+      content="Copies a setup prompt to paste into Claude Code, Cursor, or any coding agent"
+    />
+  );
+}
+
 export function TriggerDevStepV3({ title }: TabsProps) {
   const triggerCliTag = useTriggerCliTag();
   const { activePackageManager, setActivePackageManager } = usePackageManager();

apps/webapp/app/routes/api.v1.projects.$projectRef.init.ts

@@ -0,0 +1,47 @@
+import { json } from "@remix-run/server-runtime";
+import { z } from "zod";
+import { prisma } from "~/db.server";
+import { createActionPATApiRoute } from "~/services/routeBuilders/apiBuilder.server";
+
+const ParamsSchema = z.object({
+  projectRef: z.string(),
+});
+
+export const action = createActionPATApiRoute(
+  {
+    method: "POST",
+    params: ParamsSchema,
+  },
+  async ({ params, authentication }) => {
+    const project = await prisma.project.findFirst({
+      where: {
+        externalRef: params.projectRef,
+        organization: {
+          deletedAt: null,
+          members: { some: { userId: authentication.userId } },
+        },
+        deletedAt: null,
+      },
+      select: { id: true, initializedAt: true },
+    });
+
+    if (!project) {
+      return json({ error: "Project not found" }, { status: 404 });
+    }
+
+    if (!project.initializedAt) {
+      await prisma.project.updateMany({
+        where: { id: project.id, initializedAt: null },
+        data: { initializedAt: new Date() },
+      });
+    }
+
+    const { initializedAt } =
+      (await prisma.project.findFirst({
+        where: { id: project.id },
+        select: { initializedAt: true },
+      })) ?? {};
+
+    return json({ id: project.id, initializedAt: initializedAt ?? null });
+  }
+);

internal-packages/database/prisma/migrations/20260811065646_add_project_initialized_at/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "Project" ADD COLUMN "initializedAt" TIMESTAMP(3);

internal-packages/database/prisma/schema.prisma

@@ -469,6 +469,9 @@ model Project {
   updatedAt DateTime  @updatedAt
   deletedAt DateTime?
 
+  /// Set the first time the CLI `init` command completes against this project. Drives the dev onboarding progress.
+  initializedAt DateTime?
+
   version ProjectVersion   @default(V2)
   engine  RunEngineVersion @default(V1)
 

packages/cli-v3/src/apiClient.ts

@@ -95,6 +95,11 @@ const CliPlatformNotificationResponseSchema = z.object({
     .nullable(),
 });
 
+const MarkProjectInitializedResponseBody = z.object({
+  id: z.string(),
+  initializedAt: z.string().nullable(),
+});
+
 export class CliApiClient {
   private engineURL: string;
   private source: "cli" | "mcp";
@@ -174,6 +179,24 @@ export class CliApiClient {
     });
   }
 
+  async markProjectInitialized(projectRef: string) {
+    if (!this.accessToken) {
+      throw new Error("markProjectInitialized: No access token");
+    }
+
+    return wrapZodFetch(
+      MarkProjectInitializedResponseBody,
+      `${this.apiURL}/api/v1/projects/${projectRef}/init`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.accessToken}`,
+          "Content-Type": "application/json",
+        },
+      }
+    );
+  }
+
   async getProjects() {
     if (!this.accessToken) {
       throw new Error("getProjects: No access token");

packages/cli-v3/src/commands/init.ts

@@ -339,6 +339,15 @@ async function _initCommand(dir: string, options: InitCommandOptions) {
   // Ignore .trigger dir
   await gitIgnoreDotTriggerDir(dir, options);
 
+  try {
+    const result = await apiClient.markProjectInitialized(selectedProject.externalRef);
+    if (!result.success) {
+      logger.debug("Failed to mark project as initialized", { error: result.error });
+    }
+  } catch (error) {
+    logger.debug("Failed to mark project as initialized", { error });
+  }
+
   const projectDashboard = cliLink(
     "project dashboard",
     `${authorization.dashboardUrl}/projects/v3/${selectedProject.externalRef}`

packages/cli-v3/templates/examples/schedule.mjs.template

@@ -1,4 +1,4 @@
-import { logger, schedules, wait } from "@trigger.dev/sdk/v3";
+import { logger, schedules, wait } from "@trigger.dev/sdk";
 
 export const firstScheduledTask = schedules.task({
   id: "first-scheduled-task",