@agent-native/dispatch 0.6.0 → 0.7.0

package/src/server/lib/app-creation-store.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { getSetting, putSetting } from "@agent-native/core/settings";
+import { assertValidWorkspaceAppId } from "@agent-native/core/shared";
 import {
   getBuilderBranchProjectId,
   getRequestContext,
@@ -12,7 +13,6 @@ import {
   runBuilderAgent,
 } from "@agent-native/core/server";
 import { getDbExec } from "@agent-native/core/db";
-import { assertValidWorkspaceAppId } from "@agent-native/core/shared";
 import {
   currentOrgId,
   currentOwnerEmail,
@@ -28,6 +28,7 @@ import {
 } from "./workspace-resources-store.js";
 
 const SETTINGS_KEY = "dispatch-app-creation-settings";
+const WORKSPACE_APP_METADATA_SETTINGS_KEY = "workspace-app-metadata";
 const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
 const WORKSPACE_APPS_MANIFEST_FILE = "workspace-apps.json";
 const WORKSPACE_APPS_GATEWAY_PATH = "/_workspace/apps";
@@ -35,6 +36,9 @@ const WORKSPACE_APPS_GATEWAY_TIMEOUT_MS = 1_000;
 const MAX_PENDING_APPS = 50;
 const AGENT_CARD_PATH = "/.well-known/agent-card.json";
 const AGENT_CARD_FETCH_TIMEOUT_MS = 1_500;
+const DEFAULT_WORKSPACE_APP_AUDIENCE = "internal";
+
+type WorkspaceAppAudience = "internal" | "public";
 
 export interface WorkspaceAppSummary {
   id: string;
@@ -43,6 +47,9 @@ export interface WorkspaceAppSummary {
   path: string;
   url: string | null;
   isDispatch: boolean;
+  audience: WorkspaceAppAudience;
+  publicPaths: string[];
+  protectedPaths: string[];
   status?: "ready" | "pending";
   statusLabel?: string;
   builderUrl?: string | null;
@@ -64,6 +71,7 @@ export interface ListWorkspaceAppsOptions {
    * when rendering the "Hidden apps" expander.
    */
   includeArchived?: boolean;
+  audience?: WorkspaceAppAudience | "all";
 }
 
 export interface AvailableWorkspaceTemplate {
@@ -103,10 +111,24 @@ interface PendingWorkspaceApp {
   builderUrl: string | null;
   branchName: string | null;
   projectId: string | null;
+  audience?: WorkspaceAppAudience;
   createdAt: string;
   updatedAt: string;
 }
 
+interface WorkspaceAppMetadataOverride {
+  name?: string;
+  description?: string;
+  generated?: boolean;
+  sourcePrompt?: string;
+  updatedAt?: string;
+  updatedBy?: string;
+}
+
+interface WorkspaceAppMetadataSettings {
+  apps: Record<string, WorkspaceAppMetadataOverride>;
+}
+
 function readJson(file: string): any {
   try {
     return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -137,12 +159,56 @@ function titleCase(value: string): string {
     .join(" ");
 }
 
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function ensureSentence(value: string): string {
+  if (!value) return value;
+  const capitalized = value.charAt(0).toUpperCase() + value.slice(1);
+  return /[.!?]$/.test(capitalized) ? capitalized : `${capitalized}.`;
+}
+
+function clipSentence(value: string, max = 180): string {
+  if (value.length <= max) return value;
+  const clipped = value
+    .slice(0, max - 1)
+    .replace(/\s+\S*$/, "")
+    .trim();
+  return `${clipped || value.slice(0, max - 1).trim()}…`;
+}
+
+export function generateWorkspaceAppDescription(
+  prompt: string,
+  appId: string,
+): string {
+  const cleaned = normalizeWhitespace(prompt)
+    .replace(
+      /^(please\s+)?(build|create|make|generate|scaffold)\s+(me\s+|us\s+)?/i,
+      "",
+    )
+    .replace(
+      /^(an?\s+)?(workspace\s+)?(agent-native\s+)?(app|tool)\s+(that|to|for)\s+/i,
+      "",
+    )
+    .replace(/^(an?\s+)?(dashboard|workspace|agent)\s+(that|to|for)\s+/i, "");
+
+  if (!cleaned) return `Workspace app for ${titleCase(appId)}.`;
+  return clipSentence(ensureSentence(cleaned));
+}
+
 function scopedSettingsKey(): string {
   const orgId = currentOrgId();
   if (orgId) return `${SETTINGS_KEY}:org:${orgId}`;
   return `${SETTINGS_KEY}:user:${currentOwnerEmail()}`;
 }
 
+function workspaceAppMetadataSettingsKey(): string {
+  const orgId = currentOrgId();
+  if (orgId) return `${WORKSPACE_APP_METADATA_SETTINGS_KEY}:org:${orgId}`;
+  return `${WORKSPACE_APP_METADATA_SETTINGS_KEY}:user:${currentOwnerEmail()}`;
+}
+
 async function readSettingsRecord(): Promise<Record<string, any>> {
   const raw = await getSetting(scopedSettingsKey()).catch(() => null);
   return raw && typeof raw === "object" && !Array.isArray(raw)
@@ -150,6 +216,114 @@ async function readSettingsRecord(): Promise<Record<string, any>> {
     : {};
 }
 
+function cleanOptionalText(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function parseWorkspaceAppMetadataSettings(
+  raw: unknown,
+): WorkspaceAppMetadataSettings {
+  const record =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const rawApps =
+    record.apps &&
+    typeof record.apps === "object" &&
+    !Array.isArray(record.apps)
+      ? (record.apps as Record<string, unknown>)
+      : {};
+  const apps: Record<string, WorkspaceAppMetadataOverride> = {};
+
+  for (const [id, value] of Object.entries(rawApps)) {
+    if (!id.trim() || !value || typeof value !== "object") continue;
+    const item = value as Record<string, unknown>;
+    const override: WorkspaceAppMetadataOverride = {};
+    const name = cleanOptionalText(item.name);
+    const description = cleanOptionalText(item.description);
+    const sourcePrompt = cleanOptionalText(item.sourcePrompt);
+    const updatedAt = cleanOptionalText(item.updatedAt);
+    const updatedBy = cleanOptionalText(item.updatedBy);
+
+    if (name) override.name = name;
+    if (description) override.description = description;
+    if (item.generated === true) override.generated = true;
+    if (sourcePrompt) override.sourcePrompt = sourcePrompt;
+    if (updatedAt) override.updatedAt = updatedAt;
+    if (updatedBy) override.updatedBy = updatedBy;
+
+    if (Object.keys(override).length > 0) apps[id.trim()] = override;
+  }
+
+  return { apps };
+}
+
+async function readWorkspaceAppMetadataSettings(): Promise<WorkspaceAppMetadataSettings> {
+  const raw = await getSetting(workspaceAppMetadataSettingsKey()).catch(
+    () => null,
+  );
+  return parseWorkspaceAppMetadataSettings(raw);
+}
+
+async function writeWorkspaceAppMetadataOverride(input: {
+  appId: string;
+  name?: string | null;
+  description?: string | null;
+  generated?: boolean;
+  sourcePrompt?: string | null;
+  updatedBy?: string | null;
+}): Promise<WorkspaceAppMetadataSettings> {
+  const key = workspaceAppMetadataSettingsKey();
+  const current = parseWorkspaceAppMetadataSettings(
+    await getSetting(key).catch(() => null),
+  );
+  const appId = input.appId.trim();
+  const existing = current.apps[appId] ?? {};
+  const next: WorkspaceAppMetadataOverride = {
+    ...existing,
+    updatedAt: new Date().toISOString(),
+  };
+  const name = cleanOptionalText(input.name);
+  const description = cleanOptionalText(input.description);
+  const sourcePrompt = cleanOptionalText(input.sourcePrompt);
+  const updatedBy = cleanOptionalText(input.updatedBy);
+
+  if (name) next.name = name;
+  else delete next.name;
+  if (description) next.description = description;
+  else delete next.description;
+  if (input.generated === true) next.generated = true;
+  else if (input.generated === false) delete next.generated;
+  if (sourcePrompt) next.sourcePrompt = sourcePrompt;
+  if (updatedBy) next.updatedBy = updatedBy;
+
+  current.apps[appId] = next;
+  await putSetting(key, { apps: current.apps });
+  return current;
+}
+
+function applyWorkspaceAppMetadataOverride(
+  app: WorkspaceAppSummary,
+  settings: WorkspaceAppMetadataSettings,
+): WorkspaceAppSummary {
+  const override = settings.apps[app.id];
+  if (!override) return app;
+
+  const name = cleanOptionalText(override.name);
+  const description = cleanOptionalText(override.description);
+  const generated = override.generated === true;
+  const shouldApplyName = !!name && !generated;
+  const shouldApplyDescription =
+    !!description && (!generated || !cleanOptionalText(app.description));
+  if (!shouldApplyName && !shouldApplyDescription) return app;
+
+  return {
+    ...app,
+    ...(shouldApplyName ? { name } : {}),
+    ...(shouldApplyDescription ? { description } : {}),
+  };
+}
+
 function workspaceAppUrl(appPath: string): string | null {
   const base =
     process.env.WORKSPACE_GATEWAY_URL ||
@@ -180,6 +354,85 @@ function workspaceAppLink(
   }
 }
 
+function normalizeWorkspaceAppAudience(value: unknown): WorkspaceAppAudience {
+  return value === "public" ? "public" : DEFAULT_WORKSPACE_APP_AUDIENCE;
+}
+
+function normalizeWorkspaceAppPathList(value: unknown): string[] {
+  let rawPaths: unknown[] = [];
+  if (Array.isArray(value)) {
+    rawPaths = value;
+  } else if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) return [];
+    try {
+      const parsed = JSON.parse(trimmed);
+      rawPaths = Array.isArray(parsed) ? parsed : [trimmed];
+    } catch {
+      rawPaths = trimmed.split(",");
+    }
+  }
+
+  const paths = rawPaths
+    .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+    .filter((entry) => entry.startsWith("/"))
+    .map((entry) =>
+      entry.length > 1 && entry.endsWith("/") ? entry.slice(0, -1) : entry,
+    );
+  return Array.from(new Set(paths));
+}
+
+function workspaceAppAudienceFromPackageJson(
+  pkg: unknown,
+): WorkspaceAppAudience | undefined {
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) return undefined;
+  const record = pkg as Record<string, any>;
+  const config = record["agent-native"] ?? record.agentNative;
+  const nested =
+    config && typeof config === "object" && !Array.isArray(config)
+      ? (config as Record<string, any>)
+      : {};
+  const raw =
+    nested.workspaceApp?.audience ??
+    nested.workspace?.audience ??
+    nested.audience ??
+    record.workspaceAppAudience;
+  if (raw === undefined) return undefined;
+  return normalizeWorkspaceAppAudience(raw);
+}
+
+function workspaceAppRouteAccessFromPackageJson(pkg: unknown): {
+  publicPaths: string[];
+  protectedPaths: string[];
+} {
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg)) {
+    return { publicPaths: [], protectedPaths: [] };
+  }
+  const record = pkg as Record<string, any>;
+  const config = record["agent-native"] ?? record.agentNative;
+  const nested =
+    config && typeof config === "object" && !Array.isArray(config)
+      ? (config as Record<string, any>)
+      : {};
+  return {
+    publicPaths: normalizeWorkspaceAppPathList(
+      nested.workspaceApp?.publicPaths ??
+        nested.workspaceApp?.publicPagePaths ??
+        nested.workspace?.publicPaths ??
+        nested.publicPaths ??
+        record.workspaceAppPublicPaths,
+    ),
+    protectedPaths: normalizeWorkspaceAppPathList(
+      nested.workspaceApp?.protectedPaths ??
+        nested.workspaceApp?.privatePaths ??
+        nested.workspaceApp?.authRequiredPaths ??
+        nested.workspace?.protectedPaths ??
+        nested.protectedPaths ??
+        record.workspaceAppProtectedPaths,
+    ),
+  };
+}
+
 function parseWorkspaceAppsManifest(parsed: any): WorkspaceAppSummary[] | null {
   const rawApps = Array.isArray(parsed?.apps)
     ? parsed.apps
@@ -208,6 +461,12 @@ function parseWorkspaceAppsManifest(parsed: any): WorkspaceAppSummary[] | null {
           typeof entry.isDispatch === "boolean"
             ? entry.isDispatch
             : id === "dispatch",
+        audience:
+          entry.audience === undefined
+            ? DEFAULT_WORKSPACE_APP_AUDIENCE
+            : normalizeWorkspaceAppAudience(entry.audience),
+        publicPaths: normalizeWorkspaceAppPathList(entry.publicPaths),
+        protectedPaths: normalizeWorkspaceAppPathList(entry.protectedPaths),
         status: "ready",
       } satisfies WorkspaceAppSummary;
     })
@@ -228,7 +487,7 @@ function sortWorkspaceApps(a: WorkspaceAppSummary, b: WorkspaceAppSummary) {
 function parsePendingWorkspaceApps(value: unknown): PendingWorkspaceApp[] {
   if (!Array.isArray(value)) return [];
   return value
-    .map((entry) => {
+    .map((entry): PendingWorkspaceApp | null => {
       if (!entry || typeof entry !== "object") return null;
       const record = entry as Record<string, unknown>;
       const id = typeof record.id === "string" ? record.id.trim() : "";
@@ -259,6 +518,9 @@ function parsePendingWorkspaceApps(value: unknown): PendingWorkspaceApp[] {
           typeof record.projectId === "string" && record.projectId.trim()
             ? record.projectId.trim()
             : null,
+        ...(record.audience === undefined
+          ? {}
+          : { audience: normalizeWorkspaceAppAudience(record.audience) }),
         createdAt:
           typeof record.createdAt === "string" && record.createdAt.trim()
             ? record.createdAt.trim()
@@ -356,6 +618,9 @@ function pendingAppToSummary(app: PendingWorkspaceApp): WorkspaceAppSummary {
     path: app.path,
     url: app.builderUrl,
     isDispatch: false,
+    audience: app.audience ?? DEFAULT_WORKSPACE_APP_AUDIENCE,
+    publicPaths: [],
+    protectedPaths: [],
     status: "pending",
     statusLabel: "Building in Builder",
     builderUrl: app.builderUrl,
@@ -494,6 +759,8 @@ async function maybeIncludeAgentCards(
 async function recordPendingWorkspaceApp(input: {
   appId: string;
   projectId: string | null;
+  description: string;
+  sourcePrompt: string;
   branchName?: string | null;
   builderUrl?: string | null;
 }) {
@@ -505,6 +772,7 @@ async function recordPendingWorkspaceApp(input: {
     id: input.appId,
     name: titleCase(input.appId),
     description:
+      input.description ||
       "Builder is creating this app. The workspace path becomes live after the branch is merged and deployed.",
     path: `/${input.appId}`,
     builderUrl: input.builderUrl?.trim() || null,
@@ -522,6 +790,14 @@ async function recordPendingWorkspaceApp(input: {
     ].slice(0, MAX_PENDING_APPS),
   });
 
+  await writeWorkspaceAppMetadataOverride({
+    appId: input.appId,
+    description: input.description,
+    generated: true,
+    sourcePrompt: input.sourcePrompt,
+    updatedBy: currentOwnerEmail(),
+  });
+
   await recordAudit({
     action: "workspace-app.pending",
     targetType: "workspace-app",
@@ -614,11 +890,12 @@ function readWorkspaceAppsFromFilesystem(
 
   const apps = fs
     .readdirSync(appsDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
     .map((entry): WorkspaceAppSummary | null => {
       const appDir = path.join(appsDir, entry.name);
       const pkg = readJson(path.join(appDir, "package.json"));
       if (!pkg) return null;
+      const routeAccess = workspaceAppRouteAccessFromPackageJson(pkg);
       return {
         id: entry.name,
         name: pkg.displayName || titleCase(entry.name),
@@ -626,6 +903,11 @@ function readWorkspaceAppsFromFilesystem(
         path: `/${entry.name}`,
         url: workspaceAppUrl(`/${entry.name}`),
         isDispatch: entry.name === "dispatch",
+        audience:
+          workspaceAppAudienceFromPackageJson(pkg) ??
+          DEFAULT_WORKSPACE_APP_AUDIENCE,
+        publicPaths: routeAccess.publicPaths,
+        protectedPaths: routeAccess.protectedPaths,
         status: "ready",
       } satisfies WorkspaceAppSummary;
     })
@@ -689,17 +971,92 @@ async function applyArchivedAndPending(
   apps: WorkspaceAppSummary[],
   options: ListWorkspaceAppsOptions,
 ): Promise<WorkspaceAppSummary[]> {
-  const [withPending, archivedIds] = await Promise.all([
+  const [withPending, archivedIds, metadataSettings] = await Promise.all([
     appendPendingWorkspaceApps(apps),
     listArchivedAppIds(),
+    readWorkspaceAppMetadataSettings(),
   ]);
   const archivedSet = new Set(archivedIds);
-  const annotated = withPending.map((app) =>
-    archivedSet.has(app.id) ? { ...app, archived: true } : app,
-  );
+  const annotated = withPending.map((app) => {
+    const withMetadata = applyWorkspaceAppMetadataOverride(
+      app,
+      metadataSettings,
+    );
+    return archivedSet.has(app.id)
+      ? { ...withMetadata, archived: true }
+      : withMetadata;
+  });
   return options.includeArchived
-    ? annotated
-    : annotated.filter((app) => !app.archived);
+    ? filterAppsByAudience(annotated, options.audience)
+    : filterAppsByAudience(
+        annotated.filter((app) => !app.archived),
+        options.audience,
+      );
+}
+
+function filterAppsByAudience(
+  apps: WorkspaceAppSummary[],
+  audience: ListWorkspaceAppsOptions["audience"],
+): WorkspaceAppSummary[] {
+  if (!audience || audience === "all") return apps;
+  return apps.filter(
+    (app) =>
+      (app.audience ?? DEFAULT_WORKSPACE_APP_AUDIENCE) ===
+      normalizeWorkspaceAppAudience(audience),
+  );
+}
+
+export async function updateWorkspaceAppMetadata(input: {
+  appId: string;
+  name?: string | null;
+  description?: string | null;
+}): Promise<WorkspaceAppSummary> {
+  await assertCanManageAppCreationSettings();
+  const appId = input.appId.trim();
+  assertValidWorkspaceAppId(appId);
+
+  const apps = await listWorkspaceApps({
+    includeAgentCards: false,
+    includeArchived: true,
+  });
+  const app = apps.find((candidate) => candidate.id === appId);
+  if (!app) throw new Error(`Workspace app "${appId}" was not found.`);
+
+  // Treat undefined/null as "field omitted, leave existing value alone"; an
+  // explicit empty string clears the override (the app reverts to its
+  // built-in name / no description). Without this, a partial update that
+  // only touches one field silently wipes the other.
+  const name = input.name == null ? app.name : input.name.trim();
+  const description =
+    input.description == null
+      ? (app.description ?? undefined)
+      : input.description.trim();
+  await writeWorkspaceAppMetadataOverride({
+    appId,
+    name,
+    description,
+    generated: false,
+    updatedBy: currentOwnerEmail(),
+  });
+
+  await recordAudit({
+    action: "workspace-app.metadata-updated",
+    targetType: "workspace-app",
+    targetId: appId,
+    summary: `Updated workspace app details for ${name}`,
+    metadata: {
+      name,
+      descriptionConfigured: !!description,
+    },
+  });
+
+  const updated = (
+    await listWorkspaceApps({
+      includeAgentCards: false,
+      includeArchived: true,
+    })
+  ).find((candidate) => candidate.id === appId);
+  return updated ?? { ...app, name, description };
 }
 
 export async function listWorkspaceApps(
@@ -745,6 +1102,9 @@ export async function listWorkspaceApps(
             path: "/dispatch",
             url: workspaceAppUrl("/dispatch"),
             isDispatch: true,
+            audience: DEFAULT_WORKSPACE_APP_AUDIENCE,
+            publicPaths: [],
+            protectedPaths: [],
             status: "ready",
           },
         ],
@@ -1166,6 +1526,7 @@ async function remoteAppCreationAuthorization(): Promise<
 function buildWorkspaceAppPrompt(input: {
   prompt: string;
   appId?: string | null;
+  description?: string | null;
   template?: string | null;
   selectedKeys?: string[];
   selectedResources?: WorkspaceResourceOption[];
@@ -1176,6 +1537,9 @@ function buildWorkspaceAppPrompt(input: {
       input.prompt.replace(/\b(build|create|make|an?|the|app|tool)\b/gi, " "),
     ) ||
     "new-app";
+  const appDescription =
+    input.description?.trim() ||
+    generateWorkspaceAppDescription(input.prompt, appId);
   const selectedKeys = input.selectedKeys || [];
   const selectedResources = input.selectedResources || [];
   const resourceList = selectedResources.length
@@ -1192,6 +1556,7 @@ function buildWorkspaceAppPrompt(input: {
       "Create a new agent-native app in this workspace.",
       "",
       `App name: ${appId}`,
+      `App description: ${appDescription}`,
       `Template to start from: ${input.template || "starter"}`,
       `User prompt: ${input.prompt.trim()}`,
       "If the user mentions a product or company such as Granola, Loom, Superhuman, Linear, or Notion, treat it as product inspiration unless they explicitly ask to connect to that service. Do not invent or require third-party API keys like GRANOLA_API_KEY just because a product is named.",
@@ -1222,11 +1587,13 @@ function buildWorkspaceAppPrompt(input: {
       "",
       "Branch readiness requirements before handing off:",
       "- The CLI auto-fills package.json name and displayName from the app id; only edit the description / scripts / dependencies if the app actually needs more than the template provides.",
+      `- Save a concise, human-readable app description in apps/${appId}/package.json "description" so Dispatch, A2A discovery, and connected agents can describe what this app does. Use the description above or improve it based on the prompt.`,
       "- Do not add or update workspace-apps.json or .agent-native/workspace-apps.json unless the app needs an explicit external URL override; the root deploy generates the workspace app registry from apps/* and deploy metadata.",
       "- Update pnpm-lock.yaml when adding or changing dependencies so Netlify can install the branch reliably.",
       "- Update the app manifest/package/deploy metadata needed by the existing workspace deployment model; do not leave the branch relying only on uncommitted local state.",
-      "- Verify the app's agent card/A2A metadata is ready so Dispatch can discover and delegate to the app after deployment.",
-      "- Include a final verification note covering the registry entry, manifest/deploy metadata, and agent-card readiness.",
+      "- Verify the app's agent card/A2A metadata is ready so Dispatch can discover and delegate to the app after deployment. Every sibling workspace app should be usable over A2A by default through call-agent.",
+      "- Give the app agent context that sibling workspace apps are available over A2A with names and descriptions from the workspace app registry; do not hardcode a stale app list.",
+      "- Include a final verification note covering the registry entry, manifest/deploy metadata, relative same-origin routing, and agent-card readiness.",
       `When it is ready, start or update the workspace dev server and navigate the user to /${appId}.`,
     ].join("\n"),
   };
@@ -1270,6 +1637,7 @@ async function grantSelectedWorkspaceResources(input: {
 export async function startWorkspaceAppCreation(input: {
   prompt: string;
   appId?: string | null;
+  description?: string | null;
   template?: string | null;
   secretIds?: string[];
   resourceIds?: string[];
@@ -1277,6 +1645,7 @@ export async function startWorkspaceAppCreation(input: {
   const initial = buildWorkspaceAppPrompt({
     prompt: input.prompt,
     appId: input.appId,
+    description: input.description,
     template: input.template,
   });
   assertValidWorkspaceAppId(initial.appId);
@@ -1304,11 +1673,15 @@ export async function startWorkspaceAppCreation(input: {
   const built = buildWorkspaceAppPrompt({
     prompt: input.prompt,
     appId: input.appId,
+    description: input.description,
     template: input.template,
     selectedKeys,
     selectedResources,
   });
   const prompt = built.prompt;
+  const appDescription =
+    input.description?.trim() ||
+    generateWorkspaceAppDescription(input.prompt, built.appId);
 
   if (isLocal) {
     await requestSelectedVaultKeys({
@@ -1375,6 +1748,8 @@ export async function startWorkspaceAppCreation(input: {
   await recordPendingWorkspaceApp({
     appId: built.appId,
     projectId: settings.builderProjectId,
+    description: appDescription,
+    sourcePrompt: input.prompt,
     branchName: result.branchName,
     builderUrl: result.url,
   });

package/src/server/lib/env-config.ts

@@ -41,4 +41,9 @@ export const envKeys: EnvKeyConfig[] = [
     label: "WhatsApp phone number ID",
     required: false,
   },
+  {
+    key: "PYLON_API_KEY",
+    label: "Pylon API key",
+    required: false,
+  },
 ];

package/src/server/lib/onboarding-steps.ts

@@ -0,0 +1,49 @@
+/**
+ * Dispatch-specific onboarding steps.
+ *
+ * Slack/Telegram/etc. are auto-registered at order 60 by the framework when
+ * their env keys are declared `required: true` in `env-config.ts`. Without
+ * any earlier dispatch-specific step, a brand-new workspace lands on
+ * "Connect Slack" as the first visible to-do — which is intimidating before
+ * the user has even created a real app. This step nudges them at adding
+ * their first workspace app first.
+ */
+
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+import { listWorkspaceApps } from "./app-creation-store.js";
+
+let registered = false;
+
+export function registerDispatchOnboardingSteps(): void {
+  if (registered) return;
+  registered = true;
+
+  registerOnboardingStep({
+    id: "dispatch:create-first-app",
+    title: "Create your first app",
+    description:
+      "Add a workspace app like Mail, Calendar, or Slides — or describe a custom app from the Apps page.",
+    order: 5,
+    required: false,
+    methods: [
+      {
+        id: "open-apps",
+        kind: "link",
+        primary: true,
+        label: "Browse apps",
+        payload: { url: "/dispatch/apps", external: false },
+      },
+    ],
+    isComplete: async () => {
+      try {
+        const apps = await listWorkspaceApps({
+          includeAgentCards: false,
+          includeArchived: true,
+        });
+        return apps.some((app) => !app.isDispatch);
+      } catch {
+        return false;
+      }
+    },
+  });
+}