@rudderhq/agent-runtime-opencode-local 0.7.2 → 0.7.4

package/skills/app-builder/assets/scaffold/components/ui/badge.tsx

@@ -0,0 +1,27 @@
+import { cn } from "@/lib/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import * as React from "react";
+
+const badgeVariants = cva(
+  "inline-flex items-center rounded-sm border px-1.5 py-0.5 text-xs font-medium",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-primary text-primary-foreground",
+        secondary: "border-transparent bg-secondary text-secondary-foreground",
+        outline: "text-foreground",
+        success: "border-primary/20 bg-accent text-accent-foreground",
+        destructive: "border-destructive/20 bg-destructive/10 text-destructive",
+      },
+    },
+    defaultVariants: { variant: "secondary" },
+  },
+);
+
+export function Badge({
+  className,
+  variant,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement> & VariantProps<typeof badgeVariants>) {
+  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
+}

package/skills/app-builder/assets/scaffold/components/ui/button.tsx

@@ -4,18 +4,20 @@ import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
 const buttonVariants = cva(
-  "inline-flex min-h-10 items-center justify-center gap-2 rounded-lg px-4 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)] disabled:pointer-events-none disabled:opacity-50",
+  "inline-flex shrink-0 items-center justify-center gap-2 rounded-md text-foreground text-sm font-medium transition-colors outline-none focus-visible:ring-2 focus-visible:ring-ring/60 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4",
   {
     variants: {
       variant: {
-        default: "bg-[var(--primary)] text-[var(--primary-foreground)] hover:brightness-95",
-        outline: "border bg-[var(--card)] hover:bg-[var(--muted)]",
-        ghost: "hover:bg-[var(--muted)]",
-        destructive: "bg-[var(--destructive)] text-white hover:brightness-95",
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
       },
       size: {
-        default: "h-10",
-        sm: "h-9 px-3",
+        default: "h-9 px-3.5",
+        sm: "h-8 px-3 text-xs",
+        "icon-sm": "size-8",
       },
     },
     defaultVariants: {

package/skills/app-builder/assets/scaffold/components/ui/card.tsx

@@ -4,16 +4,28 @@ import * as React from "react";
 export function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
   return (
     <section
-      className={cn("rounded-xl border bg-[var(--card)] text-[var(--card-foreground)] shadow-sm", className)}
+      className={cn("rounded-lg border bg-card text-card-foreground", className)}
       {...props}
     />
   );
 }
 
 export function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("border-b px-5 py-4", className)} {...props} />;
+  return <div className={cn("flex flex-col gap-1 border-b px-4 py-3", className)} {...props} />;
 }
 
 export function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
-  return <div className={cn("p-5", className)} {...props} />;
+  return <div className={cn("p-4", className)} {...props} />;
+}
+
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h2 className={cn("m-0 text-base font-semibold", className)} {...props} />;
+}
+
+export function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn("m-0 text-sm text-muted-foreground", className)} {...props} />;
+}
+
+export function CardFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex items-center border-t px-4 py-3", className)} {...props} />;
 }

package/skills/app-builder/assets/scaffold/components/ui/empty.tsx

@@ -0,0 +1,18 @@
+import { cn } from "@/lib/utils";
+import * as React from "react";
+
+export function Empty({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex min-h-44 flex-col items-center justify-center gap-3 p-6 text-center", className)} {...props} />;
+}
+
+export function EmptyHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex max-w-sm flex-col gap-1", className)} {...props} />;
+}
+
+export function EmptyTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h3 className={cn("m-0 text-sm font-semibold", className)} {...props} />;
+}
+
+export function EmptyDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn("m-0 text-sm text-muted-foreground", className)} {...props} />;
+}

package/skills/app-builder/assets/scaffold/components/ui/field.tsx

@@ -0,0 +1,23 @@
+import { Label } from "@/components/ui/label";
+import { cn } from "@/lib/utils";
+import * as React from "react";
+
+export function FieldGroup({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col gap-4", className)} {...props} />;
+}
+
+export function Field({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("flex flex-col gap-1.5", className)} {...props} />;
+}
+
+export function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
+  return <Label className={className} {...props} />;
+}
+
+export function FieldDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn("m-0 text-xs text-muted-foreground", className)} {...props} />;
+}
+
+export function FieldError({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className={cn("m-0 text-xs text-destructive", className)} {...props} />;
+}

package/skills/app-builder/assets/scaffold/components/ui/input.tsx

@@ -7,7 +7,7 @@ export const Input = React.forwardRef<HTMLInputElement, React.ComponentProps<"in
       ref={ref}
       type={type}
       className={cn(
-        "flex h-10 w-full rounded-lg border bg-white px-3 py-2 text-sm outline-none placeholder:text-[var(--muted-foreground)] focus:ring-2 focus:ring-[var(--ring)] disabled:opacity-50",
+        "flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm outline-none transition-shadow placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring/60 disabled:cursor-not-allowed disabled:opacity-50",
         className,
       )}
       {...props}

package/skills/app-builder/assets/scaffold/components/ui/label.tsx

@@ -2,5 +2,5 @@ import { cn } from "@/lib/utils";
 import * as React from "react";
 
 export function Label({ className, ...props }: React.LabelHTMLAttributes<HTMLLabelElement>) {
-  return <label className={cn("text-sm font-medium", className)} {...props} />;
+  return <label className={cn("text-sm font-medium leading-none", className)} {...props} />;
 }

package/skills/app-builder/assets/scaffold/components/ui/separator.tsx

@@ -0,0 +1,6 @@
+import { cn } from "@/lib/utils";
+import * as React from "react";
+
+export function Separator({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div role="separator" className={cn("h-px w-full bg-border", className)} {...props} />;
+}

package/skills/app-builder/assets/scaffold/components/ui/skeleton.tsx

@@ -0,0 +1,6 @@
+import { cn } from "@/lib/utils";
+import * as React from "react";
+
+export function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn("animate-pulse rounded-sm bg-muted", className)} {...props} />;
+}

package/skills/app-builder/assets/scaffold/components/ui/table.tsx

@@ -0,0 +1,30 @@
+import { cn } from "@/lib/utils";
+import * as React from "react";
+
+export function Table({ className, ...props }: React.TableHTMLAttributes<HTMLTableElement>) {
+  return (
+    <div className="w-full overflow-x-auto">
+      <table className={cn("w-full caption-bottom text-sm", className)} {...props} />
+    </div>
+  );
+}
+
+export function TableHeader({ className, ...props }: React.HTMLAttributes<HTMLTableSectionElement>) {
+  return <thead className={cn("bg-muted/60 [&_tr]:border-b", className)} {...props} />;
+}
+
+export function TableBody({ className, ...props }: React.HTMLAttributes<HTMLTableSectionElement>) {
+  return <tbody className={cn("[&_tr:last-child]:border-0", className)} {...props} />;
+}
+
+export function TableRow({ className, ...props }: React.HTMLAttributes<HTMLTableRowElement>) {
+  return <tr className={cn("border-b transition-colors hover:bg-muted/40", className)} {...props} />;
+}
+
+export function TableHead({ className, ...props }: React.ThHTMLAttributes<HTMLTableCellElement>) {
+  return <th className={cn("h-9 px-4 text-left align-middle text-xs font-medium text-muted-foreground", className)} {...props} />;
+}
+
+export function TableCell({ className, ...props }: React.TdHTMLAttributes<HTMLTableCellElement>) {
+  return <td className={cn("px-4 py-3 align-middle", className)} {...props} />;
+}

package/skills/app-builder/assets/scaffold/components.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}

package/skills/app-builder/assets/scaffold/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/skills/app-builder/assets/scaffold/next.config.ts

@@ -1,8 +1,27 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  devIndicators: false,
   output: "standalone",
   poweredByHeader: false,
+  turbopack: {
+    root: process.cwd(),
+  },
+  webpack(config, { isServer }) {
+    if (isServer) {
+      config.externals.push((
+        { request }: { request?: string },
+        callback: (error?: Error | null, result?: string) => void,
+      ) => {
+        if (request?.startsWith("node:")) {
+          callback(null, `commonjs ${request}`);
+          return;
+        }
+        callback();
+      });
+    }
+    return config;
+  },
 };
 
 export default nextConfig;

package/skills/app-builder/assets/scaffold/package.json

@@ -17,7 +17,8 @@
     "db:migrate": "tsx scripts/migrate.ts",
     "db:seed": "tsx scripts/seed.ts",
     "data:snapshot": "tsx scripts/snapshot.ts",
-    "verify": "tsc --noEmit && vitest run && next build",
+    "ui:check": "node scripts/validate-rudder-ui.mjs",
+    "verify": "pnpm ui:check && tsc --noEmit && vitest run && next build",
     "predev": "tsx scripts/migrate.ts && tsx scripts/seed.ts"
   },
   "dependencies": {

package/skills/app-builder/assets/scaffold/rudder.app.json

@@ -13,7 +13,7 @@
     "packageManager": "managed-pnpm",
     "openPath": "/",
     "readinessPath": "/api/__rudder/health",
-    "readinessTimeoutMs": 300000
+    "readinessTimeoutMs": 600000
   },
   "data": {
     "provider": "sqlite",

package/skills/app-builder/assets/scaffold/rudder.ui.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "preset": "rudder",
+  "revision": 1,
+  "sourceOwnership": "app",
+  "appearance": {
+    "designStyle": "luma",
+    "baseColor": "neutral",
+    "accentTheme": "emerald",
+    "colorMode": "system"
+  },
+  "density": "compact"
+}

package/skills/app-builder/assets/scaffold/scripts/validate-rudder-ui.mjs

@@ -0,0 +1,50 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const requiredFiles = [
+  "components.json",
+  "app/globals.css",
+  "components/ui/button.tsx",
+  "components/ui/field.tsx",
+  "components/ui/table.tsx",
+  "components/ui/empty.tsx",
+];
+
+function fail(message) {
+  console.error(`Rudder UI preset invalid: ${message}`);
+  process.exit(1);
+}
+
+let preset;
+try {
+  preset = JSON.parse(await readFile(path.join(root, "rudder.ui.json"), "utf8"));
+} catch {
+  fail("rudder.ui.json is missing or invalid JSON");
+}
+
+if (preset?.schemaVersion !== 1 || preset?.preset !== "rudder") {
+  fail("unsupported preset identity");
+}
+if (!Number.isInteger(preset?.revision) || preset.revision < 1) {
+  fail("revision must be a positive integer");
+}
+if (preset?.sourceOwnership !== "app") {
+  fail("generated Apps must own their component source");
+}
+
+for (const relativePath of requiredFiles) {
+  try {
+    await access(path.join(root, relativePath));
+  } catch {
+    fail(`required file is missing: ${relativePath}`);
+  }
+}
+
+const css = await readFile(path.join(root, "app/globals.css"), "utf8");
+for (const token of ["--background", "--foreground", "--primary", "--destructive", "--border", "--ring", "--radius"]) {
+  if (!css.includes(`${token}:`)) fail(`semantic token is missing: ${token}`);
+}
+if (!css.includes("@theme inline")) fail("Tailwind semantic token mapping is missing");
+
+console.log(`Rudder UI preset ${preset.revision}: ok`);

package/skills/app-builder/assets/scaffold/tests/e2e/app.spec.ts

@@ -4,7 +4,7 @@ test("creates a contact and keeps it after reload", async ({ page }) => {
   const suffix = crypto.randomUUID();
   const name = `Avery ${suffix.slice(0, 8)}`;
   await page.goto("/");
-  await expect(page.getByRole("heading", { name: "Customer workspace" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Contacts", exact: true })).toBeVisible();
   await page.getByLabel("Name").fill(name);
   await page.getByLabel("Email").fill(`${suffix}@example.test`);
   await page.getByLabel("Company").fill("Acme");
@@ -14,6 +14,40 @@ test("creates a contact and keeps it after reload", async ({ page }) => {
   await expect(page.getByText(name)).toBeVisible();
 });
 
+test("ships the Rudder UI preset in system light and dark modes", async ({ browser }) => {
+  const lightPage = await browser.newPage({ colorScheme: "light" });
+  await lightPage.goto("/");
+  await expect(lightPage.getByText("Pipeline Desk")).toBeVisible();
+  const lightStyle = await lightPage.evaluate(() => {
+    const style = getComputedStyle(document.documentElement);
+    return {
+      background: getComputedStyle(document.body).backgroundColor,
+      radius: style.getPropertyValue("--radius"),
+    };
+  });
+  expect(Number.parseFloat(lightStyle.radius)).toBe(0.375);
+
+  const darkPage = await browser.newPage({ colorScheme: "dark" });
+  await darkPage.goto("/");
+  const darkBackground = await darkPage.evaluate(() => (
+    getComputedStyle(document.body).backgroundColor
+  ));
+  expect(darkBackground).not.toBe(lightStyle.background);
+  await lightPage.close();
+  await darkPage.close();
+});
+
+test("keeps the primary workflow usable at 390px", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto("/");
+  await expect(page.getByRole("heading", { name: "Contacts", exact: true })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Add contact" })).toBeVisible();
+  await expect(page.getByLabel("Search contacts")).toBeVisible();
+  await expect(page.getByRole("button", { name: "Delete Maya Chen" })).toBeVisible();
+  await expect(page.getByText("Northwind").first()).toBeVisible();
+  await expect(page.locator("nextjs-portal")).toBeHidden();
+});
+
 test("shows the empty-search state", async ({ page }) => {
   await page.goto("/");
   await page.getByLabel("Search contacts").fill("no matching record");

package/skills/app-builder/evals/evals.json

@@ -9,6 +9,7 @@
       "assertions": [
         "Does not ask the user to choose a framework, database, package manager, or process topology.",
         "Uses the maintained App Builder scaffold and SQLite persistence.",
+        "Uses the versioned Rudder UI preset and its semantic shadcn primitives instead of inventing a generic dashboard theme.",
         "Does not ask for or place email credential values in Chat or source.",
         "Includes the primary contact workflow plus import, persistence, and a production-shaped edge case in verification."
       ]
@@ -32,7 +33,7 @@
       "files": [],
       "assertions": [
         "Does not inspect or mutate real customer records merely to design the table.",
-        "Uses the existing scaffold components and avoids decorative dashboard clutter.",
+        "Uses the existing Rudder UI preset components and semantic tokens, preserves readable density, and avoids decorative dashboard clutter.",
         "Verifies the table at desktop width and a 390px viewport.",
         "Captures rendered screenshot evidence and checks an empty or error state."
       ]

package/skills/app-builder/references/design-guidelines.md

@@ -2,6 +2,11 @@
 
 Design for the user's actual workflow rather than for a technology demo.
 
+For new maintained Apps, begin with the scaffold's versioned Rudder UI preset.
+Do not replace its semantic tokens with a generic shadcn preset, a one-off
+palette, or copied host application CSS. The generated App owns its component
+source and must remain independently runnable outside Rudder.
+
 - Put the primary action and current work state above decorative summaries.
 - Use tables for operational lists, with search, meaningful filters, sorting,
   pagination when needed, empty states, and clear row actions.
@@ -11,10 +16,22 @@ Design for the user's actual workflow rather than for a technology demo.
   navigation, not both.
 - Prefer readable density for CRM and marketing data. Avoid oversized KPI cards,
   excessive gradients, glass panels, and placeholder charts.
-- Use the scaffold's component primitives and theme tokens before adding new
-  one-off styling.
+- Use the scaffold's shadcn primitives and semantic theme tokens before adding
+  new components or one-off styling. Compose `Button`, `Input`, `Field`,
+  `Table`, `Badge`, `Alert`, `Empty`, `Skeleton`, and `Separator` instead of
+  recreating those patterns with styled `div` elements.
+- Keep Rudder's default visual character: calm, dense, operational, quiet, and
+  precise. Use compact radii, low-contrast borders, restrained elevation, one
+  clear primary action, and color for state or emphasis rather than decoration.
+- Use semantic utilities such as `bg-background`, `text-foreground`,
+  `bg-muted`, and `text-destructive`. Do not hardcode product colors in
+  workflow components or add component-local dark-mode colors.
+- Treat the preset as a starting system, not a brand lock. When the brief calls
+  for a distinct brand, keep the component structure, density, accessibility,
+  and state behavior while changing the named token layer deliberately.
 - Support keyboard use, visible focus, semantic headings, accessible names, and
   error text that does not rely on color.
 - Verify at desktop width and at 390px mobile width unless the brief excludes
   mobile.
 - Show loading, empty, error, populated, and destructive-operation states.
+- Run `pnpm ui:check` before final verification for new maintained Apps.

package/skills/app-builder/references/rudder-ui-preset.md

@@ -0,0 +1,73 @@
+# Rudder UI Preset
+
+The maintained scaffold includes a versioned, source-owned shadcn preset for
+building local operator tools that feel immediately at home in Rudder.
+
+## Source Of Truth
+
+- `rudder.ui.json` identifies the preset and revision.
+- `components.json` makes the generated project a conventional shadcn project.
+- `app/globals.css` owns semantic color, radius, typography, and light/dark
+  tokens.
+- `components/ui/` owns copied component source. Generated Apps do not import
+  components or CSS from the Rudder repository at runtime.
+- `scripts/validate-rudder-ui.mjs` checks that the preset contract remains
+  present before handoff.
+
+For new Apps, use this preset without asking the user to select a shadcn style,
+base palette, accent, radius, or component library. The default is Rudder's
+spacious-but-compact `luma` character, neutral surfaces, emerald action color,
+and system light/dark mode.
+
+## Composition Rules
+
+1. Start with the shipped primitives. Extend them with variants when the same
+   need recurs; do not restyle each call site.
+2. Use semantic Tailwind utilities rather than raw color utilities. New named
+   product colors belong in the token layer.
+3. Keep normal controls between 32 and 36 pixels high, use compact radii, and
+   reserve pills for true circular or exceptional status affordances.
+4. Bind native `button`, `input`, `select`, and `textarea` text to the inherited
+   semantic foreground color so system dark mode cannot reintroduce browser-UA
+   contrast regressions.
+5. Use one primary panel or table region. Cards group independent objects or
+   actions; they are not wrappers for every section.
+6. Operational lists require search or filtering when useful, readable row
+   actions, empty/loading/error states, and horizontal containment on narrow
+   screens.
+7. Use Lucide icons for familiar actions. Icon-only controls need accessible
+   labels; icons inside buttons inherit their size from `Button`.
+8. Preserve keyboard focus, semantic headings, persistent labels, inline
+   validation, and destructive confirmation.
+
+## Appearance Boundary
+
+The preset is copied into the App as a stable creation-time baseline. It does
+not read Rudder's browser-local Appearance preferences or import host CSS at
+runtime. This keeps the App portable and prevents a later Rudder theme change
+from silently changing an independently branded product.
+
+An App may add a documented host-theme bridge later, but light/dark following
+must be optional and the standalone URL must still render correctly. Changing
+that boundary is product behavior, not an incidental styling edit.
+
+## Existing Projects
+
+Do not install or overwrite the preset in an existing project by default.
+Inspect its framework, component library, tokens, and brand first. If the user
+explicitly asks to align it with Rudder, preserve application behavior and
+choose a bounded migration:
+
+- token-only alignment when components are already coherent;
+- primitive-by-primitive alignment when a source-owned component system exists;
+- full preset adoption only when the user accepts the wider visual change.
+
+Never run a shadcn overwrite command over locally modified components without
+explicit approval and a reviewed diff.
+
+## Verification
+
+Run `pnpm ui:check`, typecheck, tests, build, and the App's Playwright suite.
+In Browser, inspect the primary workflow, loading or empty state, inline error,
+destructive action, desktop layout, 390px layout, and light/dark contrast.
+Capture the useful populated state rather than a decorative empty dashboard.

package/skills/app-builder/references/scaffold-contract.md

@@ -25,6 +25,8 @@ definition through **Apps + > Add local web project** before anything runs.
 
 - Next.js App Router, React, and TypeScript
 - Tailwind CSS with shadcn-style component source owned by the project
+- a versioned Rudder UI preset with semantic light/dark tokens and compact
+  operator-tool primitives
 - SQLite with Drizzle ORM
 - Zod at API, import, and form boundaries
 - Vitest for unit tests and Playwright for browser tests
@@ -36,6 +38,8 @@ implementation detail and must not become a user decision.
 ## Required Files And Behaviors
 
 - `rudder.app.json` uses schema version 1 and a maintained template revision.
+- `rudder.ui.json` identifies the source-owned Rudder UI preset revision;
+  `components.json` keeps the project compatible with the normal shadcn CLI.
 - `/api/__rudder/health` returns readiness only after the app can open its
   selected database.
 - `RUDDER_APP_DATA_MODE=development|production` selects the database without
@@ -64,6 +68,12 @@ manifest.
 ## Commands
 
 - `pnpm dev`: migrate the development database, then run loopback development.
+- On Windows, Rudder's managed preview may select Next.js webpack while keeping
+  `node:*` built-ins external to the server bundle. This preserves the short
+  managed dependency layout required by native package executables without
+  changing the App's website output. The managed runtime supplies the same
+  compatibility to existing revision-1 Apps without rewriting their
+  `next.config.ts`, `next-env.d.ts`, or other App-owned source files.
 - `pnpm typecheck`: TypeScript validation.
 - `pnpm test`: unit and API-contract tests.
 - `pnpm build`: production build.
@@ -73,5 +83,7 @@ manifest.
 - `pnpm data:snapshot`: copy the selected SQLite database to `data/snapshots/`
   using SQLite's backup API.
 - `pnpm verify`: typecheck, tests, and build.
+- `pnpm ui:check`: validate the maintained Rudder UI preset files and semantic
+  token contract.
 
 Formal app start must not silently migrate real data. Promotion owns that step.

package/skills/app-builder/references/verification.md

@@ -18,6 +18,12 @@ substitute a shell HTTP response for UI acceptance.
 8. Capture current screenshots of the useful final state.
 9. Materialize screenshots in Chat, Run, or Library evidence.
 
+Only after all required checks pass may the Agent report
+`verified_source_ready` for the originating App. That report is not a prose
+claim: it is a run-scoped handoff that causes Desktop to repeat its maintained
+checks, start the attested loopback process, and open the App for the user.
+Questions, partial results, and blockers must never emit the handoff.
+
 Close temporary run-owned tabs after verification. Never use the user's
 persistent app view as an Agent test fixture when that could mutate formal
 data.