orionfold-relay 0.24.1 → 0.25.0

package/dist/cli.js

@@ -1186,7 +1186,7 @@ var CURRENT_PLUGIN_API_VERSION, CAPABILITY_VALUES, ORIGIN_VALUES, PrimitivesBund
 var init_types = __esm({
   "src/lib/plugins/sdk/types.ts"() {
     "use strict";
-    CURRENT_PLUGIN_API_VERSION = "0.24";
+    CURRENT_PLUGIN_API_VERSION = "0.25";
     CAPABILITY_VALUES = ["fs", "net", "child_process", "env"];
     ORIGIN_VALUES = ["ainative-internal", "third-party"];
     PrimitivesBundleManifestSchema = z.object({
@@ -7135,7 +7135,13 @@ function getWorkspaceContext() {
     gitBranch = execFileSync2("git", ["branch", "--show-current"], {
       cwd,
       encoding: "utf-8",
-      timeout: 3e3
+      timeout: 3e3,
+      // Route git's stderr to a pipe (captured on the thrown error, then
+      // discarded) instead of inheriting the console. Without this, a
+      // non-git cwd leaks a raw `fatal: not a git repository` to a
+      // customer's first-run log before the catch swallows the exit code.
+      // Mirrors src/lib/instance/git-ops.ts run().
+      stdio: ["ignore", "pipe", "pipe"]
     }).trim() || null;
   } catch {
   }
@@ -12134,7 +12140,7 @@ async function listPendingApprovalPayloads(limit = 20) {
     const isBatchProposal = row.type === "context_proposal_batch";
     const parsedInput = parseNotificationToolInput(row.toolInput);
     let effectiveWorkflowId = row.workflowId;
-    if (!row.taskId && row.toolName === "WorkflowCheckpoint" && row.toolInput) {
+    if (!row.taskId && (row.toolName === "WorkflowCheckpoint" || row.toolName === "AskUserQuestion") && row.toolInput) {
       try {
         const parsed = typeof row.toolInput === "string" ? JSON.parse(row.toolInput) : row.toolInput;
         effectiveWorkflowId = parsed.workflowId ?? null;
@@ -12963,7 +12969,7 @@ var init_registry6 = __esm({
     init_registry5();
     init_installer();
     init_schedule_spec();
-    SUPPORTED_API_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PLUGIN_API_VERSION, "0.23"]);
+    SUPPORTED_API_VERSIONS = /* @__PURE__ */ new Set([CURRENT_PLUGIN_API_VERSION, "0.24"]);
     pluginCache = null;
     lastLoadedPluginIds = /* @__PURE__ */ new Set();
     PluginTableSchema = z16.object({
@@ -24164,6 +24170,7 @@ ${step.prompt}`;
 }
 async function executeCheckpoint(workflowId, definition, state, parentTaskId, workflowRuntimeId) {
   let previousOutput = "";
+  let userAnswer = "";
   for (let i = 0; i < definition.steps.length; i++) {
     const step = definition.steps[i];
     state.currentStepIndex = i;
@@ -24177,8 +24184,27 @@ async function executeCheckpoint(workflowId, definition, state, parentTaskId, wo
         throw new Error(`Step "${step.name}" was denied approval`);
       }
     }
-    const contextPrompt = previousOutput ? `Previous step output:
-${previousOutput}
+    userAnswer = "";
+    if (step.requiresInput) {
+      state.stepStates[i].status = "waiting_approval";
+      state.status = "paused";
+      await updateWorkflowState(workflowId, state, "paused");
+      const question = step.inputPrompt ?? step.prompt;
+      userAnswer = await waitForInput(workflowId, step.name, question);
+      state.status = "running";
+      state.stepStates[i].status = "running";
+      await updateWorkflowState(workflowId, state, "active");
+    }
+    const contextParts = [];
+    if (previousOutput) {
+      contextParts.push(`Previous step output:
+${previousOutput}`);
+    }
+    if (userAnswer.trim()) {
+      contextParts.push(`User-provided input:
+${userAnswer}`);
+    }
+    const contextPrompt = contextParts.length > 0 ? `${contextParts.join("\n\n---\n\n")}
 
 ---
 
@@ -24200,6 +24226,14 @@ ${step.prompt}` : step.prompt;
       throw new Error(`Step "${step.name}" failed: ${result.error}`);
     }
     previousOutput = result.result ?? "";
+    const hasDependents = i < definition.steps.length - 1;
+    if (hasDependents && previousOutput.trim().length === 0) {
+      state.stepStates[i].status = "failed";
+      state.stepStates[i].error = "Step produced no usable output; halting dependent steps to avoid a false completion. The agent may have refused for missing context \u2014 check its output and re-run with the needed input.";
+      throw new Error(
+        `Step "${step.name}" produced no usable output \u2014 halting workflow to avoid cascading refusals`
+      );
+    }
   }
 }
 async function executeParallel(workflowId, definition, state, parentTaskId, workflowRuntimeId) {
@@ -24729,6 +24763,33 @@ ${previousOutput.slice(0, 500)}`,
   }).where(eq44(notifications.id, notificationId));
   return false;
 }
+async function waitForInput(workflowId, stepName, question, options) {
+  const notificationId = crypto.randomUUID();
+  await db.insert(notifications).values({
+    id: notificationId,
+    taskId: null,
+    type: "permission_required",
+    title: `Workflow needs input: ${stepName}`,
+    body: question.slice(0, 500),
+    toolName: "AskUserQuestion",
+    toolInput: JSON.stringify({ question, options, workflowId, stepName }),
+    createdAt: /* @__PURE__ */ new Date()
+  });
+  const pollInterval = 2e3;
+  for (; ; ) {
+    const [notification] = await db.select().from(notifications).where(eq44(notifications.id, notificationId));
+    if (notification?.response) {
+      try {
+        const parsed = JSON.parse(notification.response);
+        const answer = parsed?.updatedInput?.answer;
+        return typeof answer === "string" ? answer : "";
+      } catch {
+        return "";
+      }
+    }
+    await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+  }
+}
 async function updateWorkflowState(workflowId, state, status) {
   const [workflow] = await db.select().from(workflows).where(eq44(workflows.id, workflowId));
   if (!workflow) throw new Error(`Workflow ${workflowId} not found \u2014 cannot update state`);
@@ -25838,8 +25899,8 @@ import { execFileSync as execFileSync3 } from "child_process";
 import yaml12 from "js-yaml";
 import semver from "semver";
 function relayCoreVersion() {
-  if (semver.valid("0.24.1")) {
-    return "0.24.1";
+  if (semver.valid("0.25.0")) {
+    return "0.25.0";
   }
   try {
     const root = getAppRoot(import.meta.dirname, 3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orionfold-relay",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Orionfold Relay — a local-first, multi-agent orchestration runtime and builder scaffold for AI-native work.",
   "keywords": [
     "ai",

package/src/components/apps/app-detail-actions.tsx

@@ -2,15 +2,9 @@
 
 import { useState, useTransition } from "react";
 import { useRouter } from "next/navigation";
-import { MoreHorizontal, Trash2 } from "lucide-react";
+import { Trash2 } from "lucide-react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
 import { ConfirmDialog } from "@/components/shared/confirm-dialog";
 
 interface AppDetailActionsProps {
@@ -76,22 +70,15 @@ export function AppDetailActions({
 
   return (
     <>
-      <DropdownMenu>
-        <DropdownMenuTrigger asChild>
-          <Button variant="ghost" size="sm" aria-label="App actions">
-            <MoreHorizontal className="h-4 w-4" aria-hidden="true" />
-          </Button>
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end">
-          <DropdownMenuItem
-            onClick={() => setConfirmOpen(true)}
-            className="text-destructive focus:text-destructive"
-          >
-            <Trash2 className="h-3.5 w-3.5 mr-2" aria-hidden="true" />
-            Delete app
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
+      <Button
+        variant="outline"
+        size="sm"
+        onClick={() => setConfirmOpen(true)}
+        className="text-destructive hover:text-destructive"
+      >
+        <Trash2 className="h-3.5 w-3.5 mr-1.5" aria-hidden="true" />
+        Delete app
+      </Button>
 
       <ConfirmDialog
         open={confirmOpen}

package/src/components/apps/kit-view/kit-view.tsx

@@ -25,7 +25,14 @@ export function KitView({ model }: KitViewProps) {
       {model.kpis && <KpisSlotView tiles={model.kpis} />}
       {model.hero && <HeroSlotView slot={model.hero} />}
       {model.secondary && model.secondary.length > 0 && (
-        <SecondarySlotView slots={model.secondary} />
+        <div className="space-y-3">
+          {model.secondaryLead && (
+            <p className="text-sm text-muted-foreground">
+              {model.secondaryLead}
+            </p>
+          )}
+          <SecondarySlotView slots={model.secondary} />
+        </div>
       )}
       {model.activity && <ActivitySlotView slot={model.activity} />}
       {model.footer && <FooterSlotView slot={model.footer} />}

package/src/components/apps/kit-view/slots/header.tsx

@@ -22,8 +22,8 @@ interface HeaderSlotProps {
 export function HeaderSlotView({ slot, manifestPane }: HeaderSlotProps) {
   const { title, description, status, actions, cadenceChip, runNowBlueprintId, runNowVariables, periodChip, triggerSourceChip } = slot;
   return (
-    <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between">
-      <div className="min-w-0">
+    <div className="flex flex-col gap-1 sm:flex-row sm:items-center sm:justify-between sm:gap-4">
+      <div className="min-w-0 flex-1">
         <h1 className="text-xl font-semibold tracking-tight line-clamp-2" title={title}>
           {title}
         </h1>
@@ -33,7 +33,7 @@ export function HeaderSlotView({ slot, manifestPane }: HeaderSlotProps) {
           </p>
         )}
       </div>
-      <div className="flex flex-wrap items-center gap-2 mt-2 sm:mt-0">
+      <div className="flex flex-wrap items-center gap-2 mt-2 sm:mt-0 sm:flex-nowrap sm:shrink-0">
         {status && <StatusChip status={status} size="md" />}
         {cadenceChip && (
           <ScheduleCadenceChip

package/src/components/apps/kit-view/slots/manifest-sheet.tsx

@@ -2,7 +2,7 @@
 
 import type { ReactNode } from "react";
 import { useState } from "react";
-import { ChevronDown, FileText } from "lucide-react";
+import { ChevronRight, FileText } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import {
   Sheet,
@@ -36,7 +36,7 @@ export function ManifestSheet({ appName, body }: ManifestSheetProps) {
       >
         <FileText className="h-3.5 w-3.5 mr-1.5" aria-hidden="true" />
         View manifest
-        <ChevronDown className="h-3.5 w-3.5 ml-1" aria-hidden="true" />
+        <ChevronRight className="h-3.5 w-3.5 ml-1" aria-hidden="true" />
       </Button>
       <Sheet open={open} onOpenChange={setOpen}>
         <SheetContent side="right" className="w-full sm:max-w-2xl overflow-hidden flex flex-col">

package/src/components/apps/last-run-card.tsx

@@ -13,10 +13,11 @@ import {
   SheetTitle,
   SheetTrigger,
 } from "@/components/ui/sheet";
-import { ChevronDown, AlertCircle } from "lucide-react";
+import { ChevronDown, AlertCircle, Sparkles, RefreshCw } from "lucide-react";
 import { ErrorBoundary } from "@/components/shared/error-boundary";
+import { RunNowButton } from "@/components/apps/run-now-button";
 import type { TaskStatus } from "@/lib/constants/task-status";
-import type { RuntimeTaskSummary } from "@/lib/apps/view-kits/types";
+import type { BlueprintCard, RuntimeTaskSummary } from "@/lib/apps/view-kits/types";
 
 interface LastRunSummary {
   id: string;
@@ -94,6 +95,94 @@ function CompactVariant({ blueprintLabel, lastRun, runCount30d }: CompactProps)
   );
 }
 
+interface RunnableBlueprintCardProps {
+  card: BlueprintCard;
+  lastRun: LastRunSummary | null;
+  runCount30d: number;
+}
+
+/**
+ * FEAT-5/6: the runnable blueprint card on the app home. Renders the
+ * blueprint's name + one-line description + last-run status + a Run action.
+ * The "Start here" card is highlighted. Row-insert blueprints label their
+ * automatic trigger instead of offering a manual Run that fights the contract.
+ */
+export function RunnableBlueprintCard({
+  card,
+  lastRun,
+  runCount30d,
+}: RunnableBlueprintCardProps) {
+  const isRowInsert = card.trigger?.kind === "row-insert";
+  return (
+    <Card
+      className={
+        card.isPrimary
+          ? "surface-card border-primary ring-1 ring-primary/30"
+          : "surface-card"
+      }
+    >
+      <CardHeader className="pb-2 space-y-1.5">
+        {card.isPrimary && (
+          <Badge className="w-fit gap-1">
+            <Sparkles className="h-3 w-3" />
+            Start here
+          </Badge>
+        )}
+        <CardTitle className="text-sm font-medium">{card.name}</CardTitle>
+        {card.description && (
+          <p className="text-xs text-muted-foreground line-clamp-2">
+            {card.description}
+          </p>
+        )}
+      </CardHeader>
+      <CardContent className="space-y-3">
+        <div className="flex items-center gap-2 flex-wrap">
+          {lastRun ? (
+            <>
+              <Badge variant={statusVariant[lastRun.status]}>
+                {lastRun.status}
+              </Badge>
+              <span className="text-xs text-muted-foreground">
+                {formatAgo(lastRun.createdAt)}
+              </span>
+            </>
+          ) : (
+            <span className="text-xs text-muted-foreground">never run</span>
+          )}
+          <span className="text-xs text-muted-foreground">
+            · {runCount30d} {runCount30d === 1 ? "run" : "runs"} · 30d
+          </span>
+        </div>
+        {isRowInsert ? (
+          <p className="flex items-center gap-1.5 text-xs text-muted-foreground">
+            <RefreshCw className="h-3.5 w-3.5" />
+            Runs on its own when you add a row to the{" "}
+            {card.trigger?.tableName ?? "linked"} table
+          </p>
+        ) : (
+          <div className="space-y-1.5">
+            <RunNowButton
+              blueprintId={card.id}
+              variables={card.variables}
+              label="Run"
+            />
+            {/* FEAT-5.2: on the "Start here" card, tell a first-time user what
+                Run does. Only the primary card carries this hint, so the grid
+                stays scannable (progressive disclosure). */}
+            {card.isPrimary && (
+              <p className="text-xs text-muted-foreground">
+                {card.variables.length > 0
+                  ? "Run asks a few questions, then starts a workflow you can watch."
+                  : "Run starts a workflow you can watch as it works."}
+              </p>
+            )}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+
 function HeroVariant({ task, previousRuns }: HeroProps) {
   const [sheetOpen, setSheetOpen] = useState(false);
 

package/src/components/apps/ledger-hero-panel.tsx

@@ -15,7 +15,8 @@ export function LedgerHeroPanel({ series, categories, period }: LedgerHeroPanelP
   if (series.length === 0 && categories.length === 0) {
     return (
       <div className="surface-card rounded-xl p-12 text-center text-muted-foreground border">
-        No data yet. Add transactions or click <strong>Run now</strong> to ingest a CSV.
+        No data yet. Click <strong>Run now</strong> to start this app&apos;s workflow.
+        Results show up here once it finishes.
       </div>
     );
   }

package/src/components/settings/license-section.tsx

@@ -53,10 +53,15 @@ function daysUntil(iso: string): number {
 }
 
 function formatDate(iso: string): string {
+  // License dates are calendar dates stored as midnight-UTC instants
+  // (e.g. "2026-07-03T00:00:00Z"). Format in UTC so a customer in a
+  // behind-UTC timezone doesn't see the date shift one day earlier than
+  // the license file and their purchase email say.
   return new Date(iso).toLocaleDateString(undefined, {
     year: "numeric",
     month: "short",
     day: "numeric",
+    timeZone: "UTC",
   });
 }
 

package/src/components/workflows/shared/workflow-header.tsx

@@ -11,11 +11,74 @@ import {
   RotateCcw,
   Trash2,
   FolderKanban,
+  ArrowRight,
+  Inbox as InboxIcon,
+  Clock3,
+  Loader2,
 } from "lucide-react";
 import { workflowStatusVariant, patternLabels } from "@/lib/constants/status-colors";
 import { IconCircle, getWorkflowIconFromName } from "@/lib/constants/card-icons";
 import type { WorkflowStatusResponse } from "@/lib/workflows/types";
 
+/**
+ * FEAT-7/8: a status-aware signpost telling the user what to do next. After a
+ * blueprint instantiates a draft, "Execute" is not obvious — so `draft` gets a
+ * "click Execute to start" nudge. Once running/paused, activity lives on other
+ * surfaces (Inbox for approvals, the steps below for progress) — so those
+ * statuses point there. A paused HITL run must read as "waiting for you", not
+ * "stuck".
+ *
+ * Distinguishing the two kinds of `paused`: a delay pause carries `resumeAt`
+ * (it resumes on its own); a HITL pause (BUG-3) sets a step to
+ * `waiting_approval` and has no resumeAt (it waits for your answer → Inbox).
+ */
+export type Signpost = {
+  tone: "info" | "wait";
+  icon: "arrow" | "inbox" | "clock" | "spinner";
+  href?: string;
+  text: string;
+} | null;
+
+export function computeSignpost(data: WorkflowStatusResponse): Signpost {
+  const status = data.status;
+  if (status === "draft") {
+    return {
+      tone: "info",
+      icon: "arrow",
+      text: "Ready to go. Click Execute to start this workflow.",
+    };
+  }
+  // A live workflow is `active` at the top level (`running` is a step/run-state
+  // value; the loop arm may report it too — accept both).
+  if (status === "active" || status === "running") {
+    return {
+      tone: "info",
+      icon: "spinner",
+      text: "Working now. Watch the steps below as it goes.",
+    };
+  }
+  if (status === "paused") {
+    // A delay pause resumes on its own; the non-loop arm carries resumeAt.
+    const resumeAt =
+      "resumeAt" in data ? (data.resumeAt as number | null) : null;
+    if (resumeAt != null) {
+      return {
+        tone: "wait",
+        icon: "clock",
+        text: "Paused for a scheduled step. It resumes on its own.",
+      };
+    }
+    // Otherwise it is waiting for your answer (HITL checkpoint → Inbox).
+    return {
+      tone: "wait",
+      icon: "inbox",
+      href: "/inbox",
+      text: "Waiting for your approval. Answer it in your Inbox.",
+    };
+  }
+  return null;
+}
+
 /**
  * Pattern-agnostic header card for the workflow detail page. Renders the
  * workflow name, pattern label, project/run badges, status badge, and the
@@ -136,6 +199,57 @@ export function WorkflowHeader({
           )}
         </div>
       </div>
+      <SignpostBanner signpost={computeSignpost(data)} />
     </CardHeader>
   );
 }
+
+/**
+ * FEAT-7/8: renders the status-aware "what to do next" banner. `wait` tone
+ * (waiting on the user) is emphasized; `info` tone is quiet. When a signpost
+ * has an href, the whole banner is a link (e.g. paused HITL → /inbox).
+ */
+function SignpostBanner({ signpost }: { signpost: Signpost }) {
+  const router = useRouter();
+  if (!signpost) return null;
+
+  const Icon =
+    signpost.icon === "inbox"
+      ? InboxIcon
+      : signpost.icon === "clock"
+        ? Clock3
+        : signpost.icon === "spinner"
+          ? Loader2
+          : ArrowRight;
+
+  const tone =
+    signpost.tone === "wait"
+      ? "border-status-warning/40 bg-status-warning/10 text-foreground"
+      : "border-border bg-muted/40 text-muted-foreground";
+
+  const body = (
+    <div
+      className={`mt-3 flex items-center gap-2 rounded-lg border px-3 py-2 text-sm ${tone} ${
+        signpost.href ? "cursor-pointer hover:bg-accent transition-colors" : ""
+      }`}
+    >
+      <Icon
+        className={`h-4 w-4 shrink-0 ${
+          signpost.icon === "spinner" ? "animate-spin" : ""
+        }`}
+      />
+      <span>{signpost.text}</span>
+      {signpost.href && <ArrowRight className="h-3.5 w-3.5 ml-auto shrink-0" />}
+    </div>
+  );
+
+  if (signpost.href) {
+    const href = signpost.href;
+    return (
+      <div role="link" tabIndex={0} onClick={() => router.push(href)}>
+        {body}
+      </div>
+    );
+  }
+  return body;
+}

package/src/lib/apps/view-kits/data.ts

@@ -7,6 +7,7 @@ import { humanizeCron } from "@/lib/apps/registry";
 import type { AppDetail, AppManifest, ViewConfig } from "@/lib/apps/registry";
 import type { ResolvedBindings } from "./resolve";
 import type {
+  BlueprintCard,
   CadenceChipData,
   HeroTableData,
   KitId,
@@ -34,6 +35,8 @@ export interface KitProjectionShape {
   kpiSpecs?: KpiSpec[];
   blueprintIds?: string[];
   scheduleIds?: string[];
+  /** FEAT-5/6: Workflow Hub — blueprint flagged "Start here" on the card home. */
+  primaryBlueprintId?: string;
   /** Phase 3: Ledger period; threaded into windowed KPI specs. */
   period?: "mtd" | "qtd" | "ytd";
   /** Phase 3: Ledger column inference for data-layer queries. */
@@ -85,6 +88,7 @@ async function loadRuntimeStateUncached(
       cadence: await loadCadence(app.manifest, undefined),
       blueprintLastRuns: await loadBlueprintLastRuns(bindings.blueprintIds),
       blueprintRunCounts: await loadBlueprintRunCounts(bindings.blueprintIds),
+      blueprintCards: await loadBlueprintCards(app.manifest, projection.primaryBlueprintId),
       failedTasks: await loadFailedTasks(app.id, 10),
       evaluatedKpis: await loadEvaluatedKpis(projection.kpiSpecs ?? []),
     };
@@ -617,6 +621,81 @@ export async function loadBlueprintVariables(
   }
 }
 
+/**
+ * FEAT-5/6: builds the runnable-card metadata for the Workflow Hub home — one
+ * card per manifest blueprint, in manifest order. Combines each manifest stub
+ * (id + trigger) with its registered definition (name + description +
+ * variables) so the card can render a name, one-line "what it does", a Run
+ * action, and honor row-insert gating.
+ *
+ * The blueprint registry is loaded via dynamic `import()` to keep this module
+ * off the runtime-catalog module-load cycle (see CLAUDE.md smoke-budget note).
+ * A blueprint whose definition is missing (not yet materialized / invalid) still
+ * gets a card — it falls back to its id for the name and offers a direct Run.
+ *
+ * `primaryBlueprintId` flags which card reads "Start here." When it doesn't
+ * match any blueprint, no card is flagged (rather than defaulting to the first,
+ * which for Agency Pro is the schedule-driven month-end-close — the wrong first
+ * click per the walkthrough).
+ */
+async function loadBlueprintCards(
+  manifest: AppManifest,
+  primaryBlueprintId: string | undefined
+): Promise<BlueprintCard[]> {
+  let getBlueprint: ((id: string) => { name?: string; description?: string; variables?: BlueprintVariable[] } | undefined) | null = null;
+  try {
+    const mod = await import("@/lib/workflows/blueprints/registry");
+    getBlueprint = mod.getBlueprint;
+  } catch {
+    getBlueprint = null;
+  }
+  // Resolve human table names for row-insert copy. Install rewrites the
+  // manifest's `intake`/`grants` ids to real UUIDs, so the raw trigger.table
+  // is unreadable ("a new 583aa0c2-… row"). The table store's `name` column
+  // carries the label. Loaded via dynamic import (same module-cycle guard).
+  const tableName = await loadTableNameResolver();
+  return manifest.blueprints.map((stub) => {
+    const def = getBlueprint?.(stub.id);
+    const trigger =
+      stub.trigger?.kind === "row-insert"
+        ? {
+            kind: "row-insert" as const,
+            table: stub.trigger.table,
+            tableName: tableName(stub.trigger.table),
+          }
+        : null;
+    return {
+      id: stub.id,
+      name: def?.name ?? stub.id,
+      description: def?.description ?? null,
+      variables: def?.variables ?? [],
+      trigger,
+      isPrimary: stub.id === primaryBlueprintId,
+    };
+  });
+}
+
+/**
+ * Returns a synchronous `id → human name` lookup for user-tables, so
+ * `loadBlueprintCards` can label row-insert triggers without an await per
+ * blueprint. Falls back to the id itself when a table isn't found (or the
+ * store is unavailable). Dynamic import keeps `data.ts` off the runtime-catalog
+ * module-load cycle (smoke-budget rule).
+ */
+async function loadTableNameResolver(): Promise<(id: string) => string> {
+  try {
+    const mod = await import("@/lib/data/tables");
+    const tables = await mod.listTables();
+    const byId = new Map<string, string>();
+    for (const t of tables) {
+      if (t.id && t.name) byId.set(t.id, t.name);
+    }
+    return (id: string) => byId.get(id) ?? id;
+  } catch {
+    return (id: string) => id;
+  }
+}
+
 // --- Phase 4: helpers ---------------------------------------------------------
 
 /** Converts milliseconds to a human-readable age string. */

package/src/lib/apps/view-kits/kits/workflow-hub.ts

@@ -1,7 +1,7 @@
 import { createElement } from "react";
 import yaml from "js-yaml";
 import { ManifestPaneBody } from "@/components/apps/kit-view/manifest-pane-body";
-import { LastRunCard } from "@/components/apps/last-run-card";
+import { RunnableBlueprintCard } from "@/components/apps/last-run-card";
 import { ErrorTimeline } from "@/components/workflows/error-timeline";
 import type { ViewConfig } from "@/lib/apps/registry";
 import type {
@@ -18,9 +18,35 @@ interface WorkflowHubProjection extends KitProjection {
   blueprintIds: string[];
   scheduleIds: string[];
   kpiSpecs: KpiSpec[];
+  primaryBlueprintId?: string;
   manifestYaml: string;
 }
 
+/**
+ * FEAT-5/6: pick the "Start here" blueprint for the card home. The recommended
+ * first click is the most rewarding manually-runnable workflow. We rank by:
+ *   1. NOT row-insert-triggered — those fire on their own, so a manual Run
+ *      fights the contract.
+ *   2. NOT the target of a schedule — a schedule-driven job (e.g. month-end
+ *      close) runs itself on cadence and is a poor, often empty, first click
+ *      (the walkthrough's BUG-2 dead end).
+ * First blueprint clearing both filters wins; then any manual blueprint; then
+ * the first blueprint. `manifest` is read directly here because `resolve()` has
+ * no registry access (that lives on the server-only data layer) — trigger +
+ * schedule shape from the manifest is enough to choose.
+ */
+function pickPrimaryBlueprintId(input: ResolveInput): string | undefined {
+  const bps = input.manifest.blueprints;
+  const scheduled = new Set(
+    input.manifest.schedules
+      .map((s) => s.runs)
+      .filter((r): r is string => typeof r === "string")
+  );
+  const manual = bps.filter((b) => b.trigger?.kind !== "row-insert");
+  const unscheduledManual = manual.filter((b) => !scheduled.has(b.id));
+  return unscheduledManual[0]?.id ?? manual[0]?.id ?? bps[0]?.id;
+}
+
 /**
  * Workflow Hub — the catch-all kit. Renders for any composed app that
  * doesn't match a more specific archetype (≥2 blueprints OR no clear hero
@@ -45,6 +71,7 @@ export const workflowHubKit: KitDefinition = {
       blueprintIds: input.manifest.blueprints.map((b) => b.id),
       scheduleIds: input.manifest.schedules.map((s) => s.id),
       kpiSpecs: input.manifest.view?.bindings?.kpis ?? [],
+      primaryBlueprintId: pickPrimaryBlueprintId(input),
       manifestYaml: yaml.dump(input.manifest, { lineWidth: 100 }),
     };
     return projection;
@@ -53,18 +80,24 @@ export const workflowHubKit: KitDefinition = {
   buildModel(proj: KitProjection, runtime: RuntimeState): ViewModel {
     const projection = proj as WorkflowHubProjection;
     const { app } = runtime;
-    const blueprintIds = projection.blueprintIds;
 
     const lastRuns = runtime.blueprintLastRuns ?? {};
     const counts = runtime.blueprintRunCounts ?? {};
 
-    const secondary = blueprintIds.map((bpId) => ({
-      id: `blueprint-${bpId}`,
-      content: createElement(LastRunCard, {
-        blueprintId: bpId,
-        blueprintLabel: bpId,
-        lastRun: lastRuns[bpId] ?? null,
-        runCount30d: counts[bpId] ?? 0,
+    // FEAT-5/6: runnable blueprint cards. Prefer the enriched cards (name +
+    // description + variables + trigger) resolved by the data layer; fall back
+    // to bare ids so the home never renders empty if enrichment failed. The
+    // "Start here" card sorts first.
+    const cards = runtime.blueprintCards ?? [];
+    const ordered = [...cards].sort(
+      (a, b) => Number(b.isPrimary) - Number(a.isPrimary)
+    );
+    const secondary = ordered.map((card) => ({
+      id: `blueprint-${card.id}`,
+      content: createElement(RunnableBlueprintCard, {
+        card,
+        lastRun: lastRuns[card.id] ?? null,
+        runCount30d: counts[card.id] ?? 0,
       }),
     }));
 
@@ -91,6 +124,12 @@ export const workflowHubKit: KitDefinition = {
         cadenceChip: runtime.cadence ?? undefined,
       },
       kpis: runtime.evaluatedKpis ?? [],
+      // FEAT-7: the blueprint-vs-workflow one-liner. Only render it when there
+      // are cards to explain, so an empty hub doesn't show a dangling lead.
+      secondaryLead:
+        secondary.length > 0
+          ? "Each card below is a workflow this app can run. Pick one and click Run to start it."
+          : undefined,
       secondary,
       activity,
       footer: {

package/src/lib/apps/view-kits/types.ts

@@ -78,6 +78,14 @@ export interface RuntimeState {
   blueprintRunCounts?: Record<string, number>;
   /** Phase 2: recent failed tasks for Workflow Hub `error-timeline`. */
   failedTasks?: RuntimeTaskSummary[];
+  /**
+   * FEAT-5/6: per-blueprint card metadata for the runnable-cards home. Name +
+   * one-line description + input variables (for the Run sheet) + trigger (for
+   * row-insert gating) + `isPrimary` ("Start here" flag). Resolved from the
+   * blueprint registry via a dynamic import so `data.ts` stays off the
+   * runtime-catalog module-load cycle (see CLAUDE.md smoke-budget note).
+   */
+  blueprintCards?: BlueprintCard[];
 
   /** Phase 3: Coach kit fields. */
   coachLatestTask?: RuntimeTaskSummary | null;
@@ -124,6 +132,30 @@ export interface HeroTableData {
   rows: UserTableRowRow[];
 }
 
+/**
+ * FEAT-5/6: metadata for one runnable blueprint card on the app home. Combines
+ * the manifest stub (id + trigger) with the registered blueprint definition
+ * (name + description + variables). `isPrimary` flags the "Start here" card.
+ */
+export interface BlueprintCard {
+  id: string;
+  /** Human name from the blueprint definition; falls back to the id. */
+  name: string;
+  /** One-line "what it does" from the blueprint definition, if any. */
+  description: string | null;
+  /** Input variables for the Run sheet; empty array = direct-POST run. */
+  variables: import("@/lib/workflows/blueprints/types").BlueprintVariable[];
+  /**
+   * How the blueprint fires. `row-insert` blueprints run automatically on new
+   * rows — the card labels that instead of offering a fighting manual Run.
+   * `table` is the raw (post-install often a UUID) table id; `tableName` is the
+   * human-readable table name for copy, resolved from the table store.
+   */
+  trigger: { kind: "row-insert"; table: string; tableName: string } | null;
+  /** The recommended first workflow, rendered with a "Start here" flag. */
+  isPrimary: boolean;
+}
+
 /** Phase 2: minimal task summary used by Workflow Hub's secondary + activity. */
 export interface RuntimeTaskSummary {
   id: string;
@@ -215,6 +247,12 @@ export interface ViewModel {
   kpis?: KpiTile[];
   hero?: HeroSlot;
   secondary?: SecondarySlot[];
+  /**
+   * FEAT-7: an optional one-line lead rendered above the secondary grid. The
+   * Workflow Hub uses it for the blueprint-vs-workflow explainer ("each card is
+   * a workflow you can run"). Plain text so it can't become a styling hatch.
+   */
+  secondaryLead?: string;
   activity?: ActivityFeedSlot;
   footer?: ManifestPaneSlot;
 }

package/src/lib/environment/workspace-context.ts

@@ -38,6 +38,12 @@ export function getWorkspaceContext(): WorkspaceContext {
         cwd,
         encoding: "utf-8",
         timeout: 3000,
+        // Route git's stderr to a pipe (captured on the thrown error, then
+        // discarded) instead of inheriting the console. Without this, a
+        // non-git cwd leaks a raw `fatal: not a git repository` to a
+        // customer's first-run log before the catch swallows the exit code.
+        // Mirrors src/lib/instance/git-ops.ts run().
+        stdio: ["ignore", "pipe", "pipe"],
       }).trim() || null;
   } catch {
     // not a git repo or git not available

package/src/lib/notifications/actionable.ts

@@ -93,9 +93,18 @@ export async function listPendingApprovalPayloads(
     const isBatchProposal = row.type === "context_proposal_batch";
     const parsedInput = parseNotificationToolInput(row.toolInput);
 
-    // For checkpoint notifications (taskId is null), extract workflowId from toolInput
+    // For workflow-posted notifications with no taskId, extract workflowId from
+    // toolInput so the item deep-links to the workflow page. Both the checkpoint
+    // approval (WorkflowCheckpoint) and the HITL ask-user (AskUserQuestion, posted
+    // by the workflow engine — see BUG-3) carry `workflowId` in toolInput. A chat
+    // task's AskUserQuestion has a taskId and flows through row.workflowId instead,
+    // so this branch only fires for the engine-posted, taskId-null case.
     let effectiveWorkflowId = row.workflowId;
-    if (!row.taskId && row.toolName === "WorkflowCheckpoint" && row.toolInput) {
+    if (
+      !row.taskId &&
+      (row.toolName === "WorkflowCheckpoint" || row.toolName === "AskUserQuestion") &&
+      row.toolInput
+    ) {
       try {
         const parsed = typeof row.toolInput === "string" ? JSON.parse(row.toolInput) : row.toolInput;
         effectiveWorkflowId = parsed.workflowId ?? null;

package/src/lib/packs/templates/relay-agency-pro/base/manifest.yaml

@@ -1,5 +1,5 @@
 id: relay-agency-pro
-version: "0.2.0"
+version: "0.3.0"
 name: Relay Agency Pro
 description: >
   The agency operating system on top of the free Relay Agency verbs: a
@@ -74,7 +74,13 @@ schedules:
     runs: relay-agency-pro--month-end-close
 
 view:
-  kit: ledger
+  # Agency Pro is a six-workflow operating system, so the app home is the
+  # multi-blueprint Workflow Hub: one runnable card per chapter with a Run
+  # action, the recommended first workflow flagged "Start here." (The finance
+  # KPI tiles below still render — the `kpis` binding is kit-agnostic.) The
+  # single-hero ledger kit hid 5 of the 6 chapters on the app's own home
+  # (FEAT-5/6, redesign 2026-07-04).
+  kit: workflow-hub
   bindings:
     hero:
       table: engagements

package/src/lib/packs/templates/relay-agency-pro/pack.yaml

@@ -1,5 +1,5 @@
 id: relay-agency-pro
-version: "0.2.0"
+version: "0.3.0"
 name: Relay Agency Pro
 author: Orionfold
 # This description renders as the what-you-get preview on the locked /packs
@@ -61,4 +61,8 @@ changelog:
     The Nonprofit deep chapter, a grant pipeline that takes every opportunity
     from fit-scored go/no-go through LOI, full application, and post-award
     restricted-funds compliance with a reporting calendar.
+  "0.3.0": >-
+    A new home screen that shows all six workflows as cards you can run with
+    one click. It tells you where to start, and each card shows its last run.
+    No more hunting through menus to find what your app can do.
 customers: []

package/src/lib/plugins/examples/echo-server/plugin.yaml

@@ -1,6 +1,6 @@
 id: echo-server
 version: 0.1.0
-apiVersion: "0.24"
+apiVersion: "0.25"
 kind: chat-tools
 name: Echo Server
 description: |

package/src/lib/plugins/examples/finance-pack/plugin.yaml

@@ -1,6 +1,6 @@
 id: finance-pack
 version: 0.1.0
-apiVersion: "0.24"
+apiVersion: "0.25"
 kind: primitives-bundle
 name: Finance Pack
 description: |

package/src/lib/plugins/examples/reading-radar/plugin.yaml

@@ -1,6 +1,6 @@
 id: reading-radar
 version: 0.1.0
-apiVersion: "0.24"
+apiVersion: "0.25"
 kind: primitives-bundle
 name: Reading Radar
 description: |

package/src/lib/plugins/registry.ts

@@ -53,7 +53,7 @@ import type { ScheduleSpec } from "@/lib/validators/schedule-spec";
 // unfixed from 0.15.0 through 0.16.0 — treat the window test's failure as
 // a release blocker, not noise). The 0.13→0.14 three-MINOR bridge is over;
 // this is the standard 2-MINOR window now.
-const SUPPORTED_API_VERSIONS = new Set([CURRENT_PLUGIN_API_VERSION, "0.23"]);
+const SUPPORTED_API_VERSIONS = new Set([CURRENT_PLUGIN_API_VERSION, "0.24"]);
 
 /** Test-helper export so the window-enforcement test can read state. */
 export function isSupportedApiVersion(apiVersion: string): boolean {

package/src/lib/plugins/sdk/types.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 // (a hardcoded copy there once drifted to "0.14" — scaffolded plugins would
 // have been disabled on load the moment the window tightened). Bump on every
 // MINOR release; api-version-window.test.ts fails if this goes stale.
-export const CURRENT_PLUGIN_API_VERSION = "0.24";
+export const CURRENT_PLUGIN_API_VERSION = "0.25";
 
 // Shared capability tuple — single source of truth used by Zod schema and
 // capability-check.ts hash derivation. Exported so consumers don't need a

package/src/lib/workflows/engine.ts

@@ -347,6 +347,7 @@ async function executeCheckpoint(
   workflowRuntimeId?: string
 ): Promise<void> {
   let previousOutput = "";
+  let userAnswer = "";
 
   for (let i = 0; i < definition.steps.length; i++) {
     const step = definition.steps[i];
@@ -365,9 +366,35 @@ async function executeCheckpoint(
       }
     }
 
-    const contextPrompt = previousOutput
-      ? `Previous step output:\n${previousOutput}\n\n---\n\n${step.prompt}`
-      : step.prompt;
+    // If step declares it needs data from the user, ask BEFORE running the agent
+    // and BLOCK (indefinitely) until answered. The run holds in `paused`; the
+    // typed answer is injected into this step's context. (BUG-3.)
+    userAnswer = "";
+    if (step.requiresInput) {
+      state.stepStates[i].status = "waiting_approval";
+      state.status = "paused";
+      await updateWorkflowState(workflowId, state, "paused");
+
+      const question = step.inputPrompt ?? step.prompt;
+      userAnswer = await waitForInput(workflowId, step.name, question);
+
+      // Answered — clear the pause and resume execution of this step.
+      state.status = "running";
+      state.stepStates[i].status = "running";
+      await updateWorkflowState(workflowId, state, "active");
+    }
+
+    const contextParts: string[] = [];
+    if (previousOutput) {
+      contextParts.push(`Previous step output:\n${previousOutput}`);
+    }
+    if (userAnswer.trim()) {
+      contextParts.push(`User-provided input:\n${userAnswer}`);
+    }
+    const contextPrompt =
+      contextParts.length > 0
+        ? `${contextParts.join("\n\n---\n\n")}\n\n---\n\n${step.prompt}`
+        : step.prompt;
 
     const result = await executeStep(
       workflowId,
@@ -388,6 +415,24 @@ async function executeCheckpoint(
     }
 
     previousOutput = result.result ?? "";
+
+    // Halt-on-refusal: an agent can "complete" while producing no usable
+    // artifact (e.g. it refused to fabricate and asked for missing data in
+    // prose). Running dependent steps on top of that empty output cascades
+    // refusals into a false `completed` with nothing on disk (the BUG-3
+    // failure mode). If this step yielded no usable output and later steps
+    // depend on it, stop loudly instead. We key on empty output — not brittle
+    // prose matching — which is exactly the "no artifact" symptom observed.
+    const hasDependents = i < definition.steps.length - 1;
+    if (hasDependents && previousOutput.trim().length === 0) {
+      state.stepStates[i].status = "failed";
+      state.stepStates[i].error =
+        "Step produced no usable output; halting dependent steps to avoid a false completion. " +
+        "The agent may have refused for missing context — check its output and re-run with the needed input.";
+      throw new Error(
+        `Step "${step.name}" produced no usable output — halting workflow to avoid cascading refusals`
+      );
+    }
   }
 }
 
@@ -1157,6 +1202,64 @@ async function waitForApproval(
   return false; // Timeout — treat as denied
 }
 
+/**
+ * Ask the user a question mid-workflow and BLOCK until they answer.
+ *
+ * Reuses the existing `AskUserQuestion` answer-carrying loop that already backs
+ * chat tasks: it writes a `permission_required` notification with
+ * `toolName:"AskUserQuestion"`, which `PermissionResponseActions` renders as a
+ * free-text/options prompt and `/api/tasks/[id]/respond` answers by writing
+ * `response.updatedInput.answer`. The Inbox surfaces it (via
+ * listPendingApprovalPayloads) deep-linked to the workflow page.
+ *
+ * Unlike waitForApproval this has NO deadline — the workflow row is marked
+ * `paused` by the caller and this poll holds until a response appears. No silent
+ * deny-on-timeout (BUG-3, operator decision: indefinite pause is the honest
+ * default). Returns the typed answer string, or "" if the response carried none.
+ */
+async function waitForInput(
+  workflowId: string,
+  stepName: string,
+  question: string,
+  options?: string[]
+): Promise<string> {
+  const notificationId = crypto.randomUUID();
+
+  await db.insert(notifications).values({
+    id: notificationId,
+    taskId: null,
+    type: "permission_required",
+    title: `Workflow needs input: ${stepName}`,
+    body: question.slice(0, 500),
+    toolName: "AskUserQuestion",
+    toolInput: JSON.stringify({ question, options, workflowId, stepName }),
+    createdAt: new Date(),
+  });
+
+  // Poll indefinitely — no deadline. The workflow is already marked `paused`, so
+  // a restart won't leave it falsely `active`; the operator answers whenever.
+  const pollInterval = 2000;
+
+  for (;;) {
+    const [notification] = await db
+      .select()
+      .from(notifications)
+      .where(eq(notifications.id, notificationId));
+
+    if (notification?.response) {
+      try {
+        const parsed = JSON.parse(notification.response);
+        const answer = parsed?.updatedInput?.answer;
+        return typeof answer === "string" ? answer : "";
+      } catch {
+        return "";
+      }
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+}
+
 
 /**
  * Update workflow state in the database.

package/src/lib/workflows/types.ts

@@ -28,6 +28,19 @@ export interface WorkflowStep {
    * a prompt/profile/runtime. See features/workflow-step-delays.md.
    */
   delayDuration?: string;
+  /**
+   * If set, the checkpoint engine pauses BEFORE running this step's agent and
+   * asks the user a question (via the existing `AskUserQuestion` notification +
+   * `/api/tasks/[id]/respond` answer loop). The typed answer is injected into
+   * the step's context prompt so the agent has the missing data. The run holds
+   * in workflow status `paused` indefinitely — no deadline, no auto-fail — until
+   * the user responds from the Inbox. Use `inputPrompt` to override the question
+   * text; when omitted, the step's own `prompt` is used as the question.
+   * See features/fix-workflow-hitl-ask-user.md (BUG-3).
+   */
+  requiresInput?: boolean;
+  /** Question text shown to the user when `requiresInput` is set. Falls back to `prompt`. */
+  inputPrompt?: string;
   /**
    * Optional declarative side-effect to apply after the step's task completes
    * successfully. Used by bulk row enrichment to write the agent's result back