@dashai/cli 0.17.0 → 0.18.1

package/dist/bin.js

@@ -1276,9 +1276,30 @@ function manifestJson(opts) {
           // table keys, and it derives the display name from the slug. A
           // `name` here would fail provisioning's table materialization (#4).
           slug: "items",
+          // `human_edit` declares how safe it is for a HUMAN to hand-edit a
+          // column directly in the Data Hub grid. Your tables are visible and
+          // editable there, and you are the only one who knows which columns
+          // your code actually depends on — a wrong edit doesn't raise an
+          // error, your module just misbehaves later. Seeded on both example
+          // fields so the vocabulary is discoverable without the docs:
+          //
+          //   'locked'  — an invariant your module maintains: the status your
+          //               state machine advances, foreign keys, external ids,
+          //               money/ledger amounts, sync cursors. Writes are
+          //               REFUSED, and `human_edit_reason` is REQUIRED.
+          //   'guarded' — a human may legitimately set it, but your module
+          //               reacts to the value (due dates you notify from, the
+          //               assignee you route to). The edit lands, after a
+          //               warning. This is the default when omitted.
+          //   'open'    — data your module never reads: notes, descriptions.
+          //               No lock, no warning.
+          //
+          // Prefer marking genuinely inert columns 'open' over leaving
+          // everything on the default — a warning on every column just trains
+          // people to click through warnings.
           fields: [
-            { slug: "title", type: "text" },
-            { slug: "done", type: "boolean" }
+            { slug: "title", type: "text", human_edit: "open" },
+            { slug: "done", type: "boolean", human_edit: "guarded" }
           ]
         }
       ]
@@ -1378,6 +1399,33 @@ const nextConfig = {
     NEXT_PUBLIC_DASHWISE_API_URL:
       process.env.NEXT_PUBLIC_DASHWISE_API_URL ?? apiUrl,
   },
+  // WHO MAY FRAME THIS MODULE.
+  //
+  // A module is designed to be embedded, and \`@dashai/sdk/platform\` treats
+  // "framed" as "embedded in Dashwise": it hides the header, nav, theme toggle
+  // and sign-out, and accepts theme + brand from the parent. Without a
+  // frame-ancestors directive ANY site can iframe a signed-in module and get a
+  // chrome-less, re-skinned copy of it \u2014 the sign-out included.
+  //
+  // Default: only the Dashwise app. Set DASHWISE_FRAME_ANCESTORS to a
+  // space-separated source list to allow others (e.g. a white-labelled host or
+  // your own portal), or to \`'none'\` for a module that is never embedded.
+  async headers() {
+    const ancestors =
+      process.env.DASHWISE_FRAME_ANCESTORS ??
+      "https://app.dashwise.dev https://app.dashwise.net";
+    return [
+      {
+        source: '/:path*',
+        headers: [
+          {
+            key: 'Content-Security-Policy',
+            value: \`frame-ancestors \${ancestors};\`,
+          },
+        ],
+      },
+    ];
+  },
 };
 export default nextConfig;
 `;
@@ -1412,7 +1460,7 @@ function gitignore() {
     ".vscode/",
     ".idea/",
     "",
-    "# DashWise-generated SDK output is regenerable from module.json",
+    "# Dashwise-generated SDK output is regenerable from module.json",
     "# (run `dashwise module generate`); keep it out of source control.",
     "/node_modules/@dashai/generated/",
     ""
@@ -1462,7 +1510,7 @@ function envLocal(apiUrl = SCAFFOLD_DEFAULT_API_URL) {
 function appLayoutTsx(opts) {
   return `export const metadata = {
   title: ${JSON.stringify(opts.name)},
-  description: ${JSON.stringify(`DashWise module: ${opts.slug}`)},
+  description: ${JSON.stringify(`Dashwise module: ${opts.slug}`)},
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -1505,7 +1553,7 @@ function readme(opts) {
 function readmeHandAuthored(opts) {
   return `# ${opts.name}
 
-A DashWise module (hand-authored). Slug: \`${opts.slug}\`.
+A Dashwise module (hand-authored). Slug: \`${opts.slug}\`.
 
 ## Get started
 
@@ -1546,9 +1594,9 @@ import { createClient, type Where } from '@dashai/sdk';
 function readmeCustom(opts) {
   return `# ${opts.name}
 
-A **custom DashWise module** \u2014 a full Next.js App Router app that
+A **custom Dashwise module** \u2014 a full Next.js App Router app that
 runs in a per-installation Fly Machine (P7 substrate). Authenticated
-via the DashWise NestJS backend through \`@dashai/sdk/auth\`.
+via the Dashwise NestJS backend through \`@dashai/sdk/auth\`.
 
 Slug: \`${opts.slug}\`.
 
@@ -1572,14 +1620,18 @@ npm run dev:next            # next dev on :3000                  (terminal 2)
 ## Architecture
 
 - **\`module.json\`** \u2014 manifest (\`module_kind: 'custom'\`, \`runtime.kind: 'machine'\`).
-- **\`middleware.ts\`** \u2014 \`withAuth\` from \`@dashai/sdk/auth/middleware\`. Redirects unauthenticated requests through the DashWise SSO flow.
+- **\`middleware.ts\`** \u2014 \`withAuth\` from \`@dashai/sdk/auth/middleware\`. Redirects unauthenticated requests through the Dashwise SSO flow.
 - **\`app/layout.tsx\`** \u2014 wraps the tree in \`<AuthProvider>\` from \`@dashai/sdk/auth/client\`.
 - **\`app/page.tsx\`** \u2014 the app's home at \`/\` (auth-gated; zero-click for platform users via \`autoSignIn\`). **This is where you build your app.**
 - **\`app/dashboard/page.tsx\`** \u2014 an additional example Server Component route, also session-gated via \`getServerSession()\`.
 
-The design is yours: edit the theme tokens in \`app/globals.css\` (they ship
-colored on purpose, as a starting point) and use any Tailwind colors or
-shadcn blocks you like. A manual "Sign in" landing page is only for a
+**The design is not a blank slate.** This module renders inside the Dashwise
+app shell, so \`app/globals.css\` ships the app's REAL theme tokens: style with
+them (\`bg-primary\`, \`text-muted-foreground\`, \`rounded-lg\`) and the module
+inherits the workspace's theme, dark mode and branding automatically. Hardcode
+a hex and you opt out of all three, permanently. Layout rules (no header, no
+nav, no \`100vh\`, one \`<h1>\`) are in \`CLAUDE.md\` \u2192 "Embedded-first UI"; reach
+for more shadcn blocks freely. A manual "Sign in" landing page is only for a
 \`public_access_allowed\` module \u2014 re-add \`'/'\` to \`middleware.ts\` publicPaths
 and drop the home's session guard to build one.
 - **\`app/api/auth/callback/route.ts\`** \u2014 exchanges the SSO one-time code for a session cookie (uses \`exchangeCode()\` from the SDK).
@@ -1652,7 +1704,7 @@ start-url call.
 `;
 }
 function middlewareTs() {
-  return `// Next.js middleware \u2014 gates every route on the DashWise session cookie.
+  return `// Next.js middleware \u2014 gates every route on the Dashwise session cookie.
 // Public routes (and /api/auth/*) bypass the redirect; everything else
 // 302s through the SSO flow when no \`dashwise.session\` cookie is set.
 import { withAuth } from '@dashai/sdk/auth/middleware';
@@ -1668,12 +1720,12 @@ export default withAuth({
   // error page instead of redirect-looping back into re-authentication.
   //
   // Building a \`public_access_allowed\` module that wants an ANONYMOUS
-  // landing page (a marketing / manual "Sign in with DashWise" screen)?
+  // landing page (a marketing / manual "Sign in with Dashwise" screen)?
   // Re-add \`'/'\` here AND make app/page.tsx public (drop its
   // getServerSession guard). See the README's "Design & home" note.
   publicPaths: ['/sign-in-error'],
   loginPath: '/api/auth/sign-in',
-  // Silent sign-in: when a signed-in DashWise user opens the module through
+  // Silent sign-in: when a signed-in Dashwise user opens the module through
   // the platform (in-app embed or the module subdomain), the SSO handshake
   // completes with zero clicks \u2014 they land straight on the page they asked
   // for, the home at \`/\` included. It never touches:
@@ -1691,29 +1743,53 @@ export const config = {
 }
 function appLayoutCustomTsx(opts) {
   return `import './globals.css';
-import { AuthProvider } from '@dashai/sdk/auth/client';
+import { AuthProvider, HostRouteSync } from '@dashai/sdk/auth/client';
+import { PlatformProvider, PLATFORM_PREPAINT_SCRIPT } from '@dashai/sdk/platform';
 import { ThemeProvider } from '@/components/theme-provider';
+import { PlatformThemeSync } from '@/components/platform-theme-sync';
 
 export const metadata = {
   title: ${JSON.stringify(opts.name)},
-  description: ${JSON.stringify(`DashWise custom module: ${opts.slug}`)},
+  description: ${JSON.stringify(`Dashwise module: ${opts.slug}`)},
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
-    <html lang="en" suppressHydrationWarning>
+    // \`data-dw-surface="embedded"\` is the SERVER default: this module normally
+    // renders inside the Dashwise app shell, where the header/nav/theme toggle
+    // already exist. The pre-paint script below only ever UPGRADES it to
+    // "standalone", so chrome can never flash on top of the app's own.
+    <html lang="en" data-dw-surface="embedded" suppressHydrationWarning>
+      <head>
+        {/* Runs before first paint: stamps data-dw-surface on <html> and
+            re-applies the cached workspace brand. Keeps \`.dw-standalone-only\`
+            correct on the very first frame \u2014 a React-only guard would pop in
+            after hydration. */}
+        <script dangerouslySetInnerHTML={{ __html: PLATFORM_PREPAINT_SCRIPT }} />
+      </head>
       <body className="antialiased">
-        <ThemeProvider
-          attribute="class"
-          defaultTheme="system"
-          enableSystem
-          disableTransitionOnChange
-        >
-          {/* sessionEndpoint points at the same-origin /api/auth/session
-              route so the host-scoped session cookie is actually sent \u2014
-              a cross-origin fetch to the API would drop it (D8). */}
-          <AuthProvider sessionEndpoint="/api/auth/session">{children}</AuthProvider>
-        </ThemeProvider>
+        <PlatformProvider>
+          <ThemeProvider
+            attribute="class"
+            defaultTheme="system"
+            enableSystem
+            disableTransitionOnChange
+          >
+            {/* Follows the Dashwise app's light/dark choice when embedded.
+                Bridges the SDK to next-themes so the SDK stays theming-library
+                agnostic. Inert when standalone \u2014 your own toggle wins there. */}
+            <PlatformThemeSync />
+            {/* sessionEndpoint points at the same-origin /api/auth/session
+                route so the host-scoped session cookie is actually sent \u2014
+                a cross-origin fetch to the API would drop it (D8). */}
+            <AuthProvider sessionEndpoint="/api/auth/session">
+              {/* Mirrors in-module navigation to the Dashwise host's address
+                  bar when embedded; inert when standalone. */}
+              <HostRouteSync />
+              {children}
+            </AuthProvider>
+          </ThemeProvider>
+        </PlatformProvider>
       </body>
     </html>
   );
@@ -1721,40 +1797,37 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 `;
 }
 function appPageCustomTsx(opts) {
-  return `// app/page.tsx \u2014 the app's REAL home, served at \`/\`. THIS IS YOUR APP.
-// Build it here.
+  return `// app/page.tsx \u2014 your module's REAL home, served at \`/\`. Build it here.
 //
-// A signed-in DashWise user who opens this module through the platform
-// (in-app embed or the module subdomain) lands on THIS page with zero
-// clicks: the middleware's \`autoSignIn\` completes the SSO handshake
-// silently, so there is no sign-in wall in front of your app. The guard
-// below mirrors app/dashboard/page.tsx \u2014 no session \u2192 bounce through the
-// SSO flow and come right back to \`/\`.
+// A signed-in Dashwise user who opens this module through the platform (the
+// in-app embed or the module subdomain) lands on THIS page with zero clicks:
+// the middleware's \`autoSignIn\` completes the SSO handshake silently, so there
+// is no sign-in wall in front of your app.
 //
-// A public, anonymous sign-in landing page is only for a
-// \`public_access_allowed\` module that wants an unauthenticated entry
-// point. To build one, re-add \`'/'\` to middleware.ts publicPaths and drop
-// the getServerSession guard here (see the README's "Design & home" note).
+// \u2500\u2500\u2500 READ THIS BEFORE YOU REDESIGN THE PAGE \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// This module normally renders as a full-bleed IFRAME inside the Dashwise app
+// shell. The header, sidebar, workspace switcher, user menu, theme toggle and
+// global search ALREADY EXIST around you. So:
 //
-// The design is YOURS to own. These shadcn primitives sit on the theme
-// tokens in app/globals.css \u2014 edit the hues freely \u2014 and the full
-// Tailwind palette (bg-indigo-600, text-emerald-500, \u2026) is available too.
-// This colored starter look is a starting point, not a mandate.
-import Link from 'next/link';
+//   \xB7 no logo, no top nav, no sidebar, no footer, no theme toggle, no sign-out
+//   \xB7 no \`min-h-screen\` / \`h-screen\` / \`100vh\` \u2014 you are not the screen
+//   \xB7 exactly ONE <h1> per screen, and one primary action
+//   \xB7 style with TOKENS (bg-primary, text-muted-foreground, rounded-lg) \u2014 never
+//     a raw hex/px, or the module stops inheriting the workspace's theme
+//
+// \`ModuleShell\` below encodes all of that. Anything that should appear only
+// when the module is opened on its own subdomain goes in \`.dw-standalone-only\`.
+// See CLAUDE.md \u2192 "Embedded-first UI" for the full contract.
 import { getServerSession } from '@dashai/sdk/auth/server';
 import { redirect } from 'next/navigation';
-import { ArrowRight, Table2, Database, PenLine } from 'lucide-react';
+import { PlusIcon } from 'lucide-react';
 import { Button } from '@/components/ui/button';
-import {
-  Card,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from '@/components/ui/card';
+import { ModuleShell } from '@/components/module-shell';
+import { EmptyState } from '@/components/states';
 
 // force-dynamic: this page calls getServerSession() at render, which
 // reads DASHWISE_API_URL/KEY. \`next build\` statically PRERENDERS pages by
-// default and runs with NO DashWise env, so the SDK would throw
+// default and runs with NO Dashwise env, so the SDK would throw
 // "missing apiBaseUrl" and the platform's first publish would fail with
 // an opaque BUILD_FAILED. Opting into dynamic rendering skips prerender.
 export const dynamic = 'force-dynamic';
@@ -1764,76 +1837,32 @@ export default async function Home() {
   if (!session) {
     redirect('/api/auth/sign-in?return_to=/');
   }
+
+  // Replace this with your real first screen: list what the user came to see,
+  // and render EmptyState only while there is genuinely nothing yet. Keep the
+  // loading state (ListSkeleton) and error state (ErrorState) \u2014 they're in
+  // components/states.tsx and they are what makes a module feel finished.
   return (
-    <main className="mx-auto flex min-h-dvh max-w-4xl flex-col gap-10 px-6 py-12">
-      {/* Primary-colored hero \u2014 the default look is colored on purpose,
-          to signal the design is yours to change. */}
-      <section className="flex flex-col gap-4 rounded-2xl bg-primary px-8 py-12 text-primary-foreground shadow-sm">
-        <p className="text-sm font-medium uppercase tracking-wide opacity-80">
-          ${escapeHtml(opts.name)}
-        </p>
-        <h1 className="text-balance text-4xl font-semibold tracking-tight sm:text-5xl">
-          Your app starts here.
-        </h1>
-        <p className="max-w-xl text-pretty text-lg opacity-90">
-          Signed in as{' '}
-          <span className="font-medium">{session.user.email}</span>. This is the
-          real home of your module \u2014 edit{' '}
-          <code className="rounded bg-primary-foreground/15 px-1.5 py-0.5 font-mono">
-            app/page.tsx
-          </code>{' '}
-          to build it.
-        </p>
-        <div className="flex flex-wrap gap-3 pt-2">
-          <Button asChild size="lg" variant="secondary">
-            <Link href="/dashboard">
-              See the example route
-              <ArrowRight aria-hidden="true" />
-            </Link>
+    <ModuleShell
+      title="${escapeHtml(opts.name)}"
+      primaryAction={
+        <Button>
+          <PlusIcon aria-hidden="true" />
+          Add item
+        </Button>
+      }
+    >
+      <EmptyState
+        title="Nothing here yet"
+        description="This is your module's home. Build the first screen in app/page.tsx \u2014 declare your tables with \`dashwise table create\`, then read them with the typed \`db\` client from @dashai/generated."
+        action={
+          <Button>
+            <PlusIcon aria-hidden="true" />
+            Add item
           </Button>
-        </div>
-      </section>
-
-      {/* A few colored pointers to get moving. */}
-      <section className="grid gap-4 sm:grid-cols-3">
-        <Card className="border-l-4 border-l-chart-1">
-          <CardHeader>
-            <Table2 className="size-5 text-chart-1" aria-hidden="true" />
-            <CardTitle className="text-base">Declare your data</CardTitle>
-            <CardDescription>
-              Add tables to{' '}
-              <code className="rounded bg-muted px-1 py-0.5 font-mono">module.json</code>{' '}
-              (or run{' '}
-              <code className="rounded bg-muted px-1 py-0.5 font-mono">dashwise table create</code>).
-            </CardDescription>
-          </CardHeader>
-        </Card>
-        <Card className="border-l-4 border-l-chart-2">
-          <CardHeader>
-            <Database className="size-5 text-chart-2" aria-hidden="true" />
-            <CardTitle className="text-base">Read it, typed</CardTitle>
-            <CardDescription>
-              Import{' '}
-              <code className="rounded bg-muted px-1 py-0.5 font-mono">db</code>{' '}
-              from{' '}
-              <code className="rounded bg-muted px-1 py-0.5 font-mono">@dashai/generated</code>{' '}
-              \u2014 regenerated on every manifest save.
-            </CardDescription>
-          </CardHeader>
-        </Card>
-        <Card className="border-l-4 border-l-chart-3">
-          <CardHeader>
-            <PenLine className="size-5 text-chart-3" aria-hidden="true" />
-            <CardTitle className="text-base">Write via server actions</CardTitle>
-            <CardDescription>
-              Mutate data from Server Actions / route handlers so the scoped{' '}
-              <code className="rounded bg-muted px-1 py-0.5 font-mono">dwk_</code>{' '}
-              key stays server-side.
-            </CardDescription>
-          </CardHeader>
-        </Card>
-      </section>
-    </main>
+        }
+      />
+    </ModuleShell>
   );
 }
 `;
@@ -1843,6 +1872,7 @@ function appDashboardPageTsx() {
 import { redirect } from 'next/navigation';
 import { LogOut, ShieldCheck } from 'lucide-react';
 import { Button } from '@/components/ui/button';
+import { ModuleShell } from '@/components/module-shell';
 import {
   Card,
   CardContent,
@@ -1853,14 +1883,16 @@ import {
 
 /**
  * An ADDITIONAL example route \u2014 your real home is app/page.tsx (\`/\`).
- * This \`/dashboard\` page is here to show a second auth-gated Server
- * Component: keep it, rename it, or delete it. The middleware ensures the
- * user has a session cookie before this page renders; \`getServerSession()\`
- * validates the cookie against the backend's \`/api/auth/sessions/me\`
- * endpoint, returning the decoded \`Session\` (or \`null\` if stale).
+ * This \`/dashboard\` page shows a second auth-gated Server Component: keep
+ * it, rename it, or delete it. The middleware ensures the user has a session
+ * cookie before this page renders; \`getServerSession()\` validates the cookie
+ * against the backend's \`/api/auth/sessions/me\` endpoint, returning the
+ * decoded \`Session\` (or \`null\` if stale).
  *
- * On a successful render, this is the polished session card \u2014 replace
- * the contents with whatever your module actually needs to show.
+ * Note the shape: \`ModuleShell\` (one <h1>, app-matching padding, no 100vh)
+ * and a sign-out control wrapped in \`.dw-standalone-only\` \u2014 inside the
+ * Dashwise app the user menu already offers sign-out, so rendering our own
+ * would duplicate the app's chrome. See CLAUDE.md \u2192 "Embedded-first UI".
  */
 // force-dynamic: same reason as app/page.tsx \u2014 this route calls
 // getServerSession() at render, which needs DASHWISE_API_URL/KEY. Static
@@ -1873,23 +1905,19 @@ export default async function Dashboard() {
     redirect('/api/auth/sign-in?return_to=/');
   }
   return (
-    <main className="mx-auto flex min-h-dvh max-w-3xl flex-col gap-6 px-6 py-12">
-      <header className="flex items-start justify-between gap-4">
-        <div>
-          <h1 className="text-2xl font-semibold tracking-tight">Dashboard</h1>
-          <p className="text-sm text-muted-foreground">
-            You're signed in. This page is rendered as a Server Component and
-            validates the session cookie on every request.
-          </p>
-        </div>
-        <form action="/api/auth/sign-out" method="POST">
+    <ModuleShell
+      title="Dashboard"
+      description="Rendered as a Server Component; the session cookie is validated on every request."
+      width="narrow"
+      actions={
+        <form action="/api/auth/sign-out" method="POST" className="dw-standalone-only">
           <Button variant="outline" size="sm" type="submit">
             <LogOut aria-hidden="true" />
             Sign out
           </Button>
         </form>
-      </header>
-
+      }
+    >
       <Card>
         <CardHeader>
           <CardTitle className="flex items-center gap-2">
@@ -1918,36 +1946,7 @@ export default async function Dashboard() {
           )}
         </CardContent>
       </Card>
-
-      <Card>
-        <CardHeader>
-          <CardTitle>Next steps</CardTitle>
-          <CardDescription>
-            This is an extra example route \u2014 your real home is{' '}
-            <code className="rounded bg-muted px-1.5 py-0.5">app/page.tsx</code>.
-            Keep, rename, or delete this one.
-          </CardDescription>
-        </CardHeader>
-        <CardContent className="space-y-2 text-sm text-muted-foreground">
-          <p>
-            <strong className="text-foreground">1.</strong> Edit{' '}
-            <code className="rounded bg-muted px-1.5 py-0.5">module.json</code>{' '}
-            to add tables, dependencies, and exposed actions.
-          </p>
-          <p>
-            <strong className="text-foreground">2.</strong> Import typed clients
-            from{' '}
-            <code className="rounded bg-muted px-1.5 py-0.5">@dashai/generated</code>{' '}
-            (regenerated on every manifest save).
-          </p>
-          <p>
-            <strong className="text-foreground">3.</strong> Run{' '}
-            <code className="rounded bg-muted px-1.5 py-0.5">dashwise module publish --bump patch</code>{' '}
-            when you're ready to ship.
-          </p>
-        </CardContent>
-      </Card>
-    </main>
+    </ModuleShell>
   );
 }
 
@@ -1965,7 +1964,7 @@ function appApiAuthSignInTs() {
   return `// /api/auth/sign-in \u2014 kick off the SSO flow (one path, dev + prod).
 //
 // Reads \`?return_to=\` from the caller (defaults to '/'), then asks the
-// DashWise backend for a redirect URL by calling the module-API
+// Dashwise backend for a redirect URL by calling the module-API
 // server-side start endpoint:
 //
 //   POST /api/module-api/sso/start-url
@@ -2002,7 +2001,7 @@ export async function GET(request: Request) {
   const returnTo = url.searchParams.get('return_to') ?? '/';
   // \`auto=1\` marks a SILENT attempt (the middleware's autoSignIn redirect,
   // no user click). Its failures degrade to the public landing page \u2014 where
-  // the manual "Sign in with DashWise" button lives \u2014 instead of the error
+  // the manual "Sign in with Dashwise" button lives \u2014 instead of the error
   // page: the user never asked for anything, so don't show them an error.
   const isAuto = url.searchParams.get('auto') === '1';
   const apiBaseUrl = process.env.DASHWISE_API_URL;
@@ -2173,7 +2172,7 @@ async function tryDevHandoff(
 }
 function appApiAuthCallbackTs() {
   return `// /api/auth/callback \u2014 receives \`?code=&return_to=\` from the
-// DashWise SSO start endpoint OR \`?error=&error_description=\` if the
+// Dashwise SSO start endpoint OR \`?error=&error_description=\` if the
 // SSO flow failed. Two paths:
 //
 //   1. Success path: exchange \`?code\` for a session cookie via
@@ -2322,7 +2321,7 @@ function appApiAuthSessionTs() {
   return `// /api/auth/session \u2014 SAME-ORIGIN session probe for client components.
 //
 // D8: the browser's <AuthProvider> can't read the session by calling the
-// cross-origin DashWise API directly, because the \`dashwise.session\`
+// cross-origin Dashwise API directly, because the \`dashwise.session\`
 // cookie is host-scoped to THIS module's origin and is never sent to
 // \`api.dashwise.net\`. So <AuthProvider sessionEndpoint="/api/auth/session">
 // hits this route (same origin \u2192 the cookie IS sent); we validate it
@@ -2360,12 +2359,15 @@ function packageJsonCustom(opts) {
         start: "next start"
       },
       dependencies: {
-        "@dashai/sdk": "^2.3.0",
+        // >=2.4.0 for `@dashai/sdk/platform`, which app/layout.tsx imports. A
+        // ^2.3.0 floor resolves to 2.3.0 until 2.4.0 publishes, failing the
+        // first `next build` with an opaque module-not-found.
+        "@dashai/sdk": "^2.4.0",
         next: "^15.0.0",
         react: "^19.0.0",
         "react-dom": "^19.0.0",
         // Styling system — same shadcn + Tailwind 4 stack as the
-        // main DashWise frontend, so look-and-feel stays consistent
+        // main Dashwise frontend, so look-and-feel stays consistent
         // and module authors can add more blocks via the
         // shadcn-studio MCP (`npx shadcn add @shadcn-studio/...`).
         tailwindcss: "^4",
@@ -2439,11 +2441,18 @@ export default config;
 `;
 }
 function globalsCss() {
-  return `/* These theme tokens are a STARTING POINT \u2014 change the hues freely.
-   The default \`--primary\` is a violet/indigo and the \`--chart-*\` ramp is
-   a 5-hue set; swap them for your brand. The full Tailwind color palette
-   (bg-indigo-600, text-emerald-500, \u2026) is also available on top of these
-   tokens. This is YOUR design to own. */
+  return `/* Dashwise design tokens \u2014 the SAME values the Dashwise app uses.
+   This is the entire mechanism by which a module looks like it belongs
+   inside Dashwise: style with the TOKEN (\`bg-primary\`, \`text-muted-foreground\`,
+   \`rounded-lg\`, \`border-border\`), never a raw hex/px/shadow, and the module
+   inherits the app's look \u2014 and every future theme change \u2014 for free.
+
+   Hardcoding a colour opts out of that permanently. If you're typing \`#\`,
+   \`oklch(\`, \`rounded-[\` or \`shadow-[\` in a component, there is a token for it.
+
+   \`--primary\` and \`--brand-accent\` are additionally overridden at runtime by
+   the workspace's branding (via @dashai/sdk/platform) \u2014 which is why a module
+   that uses the tokens picks up white-labelling with no code changes. */
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
@@ -2457,39 +2466,74 @@ function globalsCss() {
   --card-foreground: oklch(0.14 0 0);
   --popover: oklch(1 0 0);
   --popover-foreground: oklch(0.14 0 0);
-  /* Colored primary (violet/indigo, ~indigo-600). White foreground reads
-     cleanly on it (~5:1). Change the hue (275) to re-brand. */
-  --primary: oklch(0.55 0.22 275);
-  --primary-foreground: oklch(0.985 0 0);
-  /* secondary + muted stay near-neutral (clean UI) but carry a faint
-     violet tint so nothing is pure grayscale. */
-  --secondary: oklch(0.97 0.005 275);
-  --secondary-foreground: oklch(0.25 0.02 275);
-  --muted: oklch(0.97 0.005 275);
-  --muted-foreground: oklch(0.55 0.02 275);
-  /* accent = a soft, low-chroma wash of the primary hue. */
-  --accent: oklch(0.96 0.03 275);
-  --accent-foreground: oklch(0.4 0.1 275);
+  --primary: #4f46e5;
+  --primary-foreground: oklch(0.99 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.2 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.5 0 0);
+  --accent: oklch(0.96 0 0);
+  --accent-foreground: oklch(0.14 0 0);
+  /* A SECONDARY brand colour, distinct from the neutral --accent hover
+     surface above. Workspace branding drives this one; never re-point
+     --accent at a brand colour or every hover state in the app gets tinted. */
+  --brand-accent: #4f46e5;
+  --brand-accent-foreground: #ffffff;
   --destructive: oklch(0.58 0.24 28.48);
+  --success: oklch(0.53 0.15 145);
+  --success-foreground: oklch(0.99 0 0);
+  --warning: oklch(0.63 0.15 62);
+  --warning-foreground: oklch(0.99 0 0);
   --border: oklch(0.92 0 0);
   --input: oklch(0.92 0 0);
-  --ring: oklch(0.55 0.2 275);
-  --radius: 0.625rem;
-
-  /* 5-hue chart ramp \u2014 distinct, readable hues for data viz + accents.
-     Wired to \`bg-chart-1\` \u2026 \`text-chart-5\` via the @theme block below. */
-  --chart-1: oklch(0.55 0.2 275);
-  --chart-2: oklch(0.6 0.13 195);
-  --chart-3: oklch(0.7 0.16 70);
-  --chart-4: oklch(0.65 0.17 145);
-  --chart-5: oklch(0.6 0.22 15);
+  --ring: #4f46e5;
+  --chart-1: oklch(0.65 0.22 36.85);
+  --chart-2: oklch(0.6 0.11 184.15);
+  --chart-3: oklch(0.4 0.07 227.18);
+  --chart-4: oklch(0.83 0.17 81.03);
+  --chart-5: oklch(0.77 0.17 65.36);
+
+  /* Option colours \u2014 the palette for single_select / multi_select values and
+     any status chip. Stable across themes. Use these instead of inventing a
+     colour for a status, so labels match the app's. */
+  --option-slate: oklch(0.55 0.041 257.4);
+  --option-red: oklch(0.637 0.208 25.3);
+  --option-dark-red: oklch(0.443 0.177 26.9);
+  --option-orange: oklch(0.705 0.191 47.6);
+  --option-amber: oklch(0.769 0.166 70.1);
+  --option-yellow: oklch(0.852 0.176 91.7);
+  --option-green: oklch(0.696 0.149 162.5);
+  --option-blue: oklch(0.623 0.214 259.8);
+  --option-indigo: oklch(0.585 0.222 277.1);
+  --option-purple: oklch(0.627 0.265 303.9);
+  --option-pink: oklch(0.656 0.241 354.3);
+
+  --code-bg: oklch(0.14 0 0);
+  --code-fg: oklch(0.97 0 0);
 
   --font-sans:
-    ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
-    "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    "Geist", "Geist Fallback", ui-sans-serif, system-ui, -apple-system,
+    BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial,
+    "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+    "Segoe UI Symbol", "Noto Color Emoji";
   --font-mono:
-    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
-    "Liberation Mono", "Courier New", monospace;
+    "Geist Mono", "Geist Mono Fallback", ui-monospace, SFMono-Regular, Menlo,
+    Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+
+  --radius: 0.625rem;
+
+  --shadow-2xs: 0 1px 3px 0px oklch(0 0 0 / 0.05);
+  --shadow-xs: 0 1px 3px 0px oklch(0 0 0 / 0.05);
+  --shadow-sm:
+    0 1px 3px 0px oklch(0 0 0 / 0.1), 0 1px 2px -1px oklch(0 0 0 / 0.1);
+  --shadow: 0 1px 3px 0px oklch(0 0 0 / 0.1), 0 1px 2px -1px oklch(0 0 0 / 0.1);
+  --shadow-md:
+    0 1px 3px 0px oklch(0 0 0 / 0.1), 0 2px 4px -1px oklch(0 0 0 / 0.1);
+  --shadow-lg:
+    0 1px 3px 0px oklch(0 0 0 / 0.1), 0 4px 6px -1px oklch(0 0 0 / 0.1);
+  --shadow-xl:
+    0 1px 3px 0px oklch(0 0 0 / 0.1), 0 8px 10px -1px oklch(0 0 0 / 0.1);
+  --shadow-2xl: 0 1px 3px 0px oklch(0 0 0 / 0.25);
 }
 
 .dark {
@@ -2499,26 +2543,31 @@ function globalsCss() {
   --card-foreground: oklch(0.99 0 0);
   --popover: oklch(0.2 0 0);
   --popover-foreground: oklch(0.99 0 0);
-  /* Slightly lighter violet so it pops on the dark background; white
-     foreground stays readable (~4.8:1). */
-  --primary: oklch(0.58 0.21 275);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.27 0.01 275);
+  --primary: #6253f0;
+  --primary-foreground: #ffffff;
+  --secondary: oklch(0.27 0 0);
   --secondary-foreground: oklch(0.99 0 0);
-  --muted: oklch(0.27 0.01 275);
-  --muted-foreground: oklch(0.71 0.02 275);
-  --accent: oklch(0.3 0.04 275);
-  --accent-foreground: oklch(0.97 0.01 275);
+  --muted: oklch(0.27 0 0);
+  --muted-foreground: oklch(0.71 0 0);
+  --accent: oklch(0.27 0 0);
+  --accent-foreground: oklch(0.99 0 0);
+  --brand-accent: #6253f0;
+  --brand-accent-foreground: #ffffff;
   --destructive: oklch(0.7 0.19 22.23);
-  --border: oklch(0.27 0 0);
-  --input: oklch(0.27 0 0);
-  --ring: oklch(0.58 0.19 275);
-
-  --chart-1: oklch(0.62 0.19 275);
-  --chart-2: oklch(0.67 0.13 195);
-  --chart-3: oklch(0.75 0.15 70);
-  --chart-4: oklch(0.7 0.16 145);
-  --chart-5: oklch(0.67 0.2 15);
+  --success: oklch(0.65 0.16 145);
+  --success-foreground: oklch(0.14 0 0);
+  --warning: oklch(0.75 0.15 62);
+  --warning-foreground: oklch(0.14 0 0);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: #6253f0;
+  --chart-1: oklch(0.49 0.24 264.4);
+  --chart-2: oklch(0.7 0.16 160.43);
+  --chart-3: oklch(0.77 0.17 65.36);
+  --chart-4: oklch(0.62 0.26 305.32);
+  --chart-5: oklch(0.64 0.25 16.51);
+  --code-bg: oklch(0.2 0 0);
+  --code-fg: oklch(0.97 0 0);
 }
 
 /* Wire EVERY design token into Tailwind's namespace. In Tailwind 4,
@@ -2542,7 +2591,13 @@ function globalsCss() {
   --color-muted-foreground: var(--muted-foreground);
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
+  --color-brand-accent: var(--brand-accent);
+  --color-brand-accent-foreground: var(--brand-accent-foreground);
   --color-destructive: var(--destructive);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
@@ -2551,10 +2606,33 @@ function globalsCss() {
   --color-chart-3: var(--chart-3);
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
+  --color-option-slate: var(--option-slate);
+  --color-option-red: var(--option-red);
+  --color-option-dark-red: var(--option-dark-red);
+  --color-option-orange: var(--option-orange);
+  --color-option-amber: var(--option-amber);
+  --color-option-yellow: var(--option-yellow);
+  --color-option-green: var(--option-green);
+  --color-option-blue: var(--option-blue);
+  --color-option-indigo: var(--option-indigo);
+  --color-option-purple: var(--option-purple);
+  --color-option-pink: var(--option-pink);
+  --color-code-bg: var(--code-bg);
+  --color-code-fg: var(--code-fg);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
   --radius-sm: calc(var(--radius) - 4px);
   --radius-md: calc(var(--radius) - 2px);
   --radius-lg: var(--radius);
   --radius-xl: calc(var(--radius) + 4px);
+  --shadow-2xs: var(--shadow-2xs);
+  --shadow-xs: var(--shadow-xs);
+  --shadow-sm: var(--shadow-sm);
+  --shadow: var(--shadow);
+  --shadow-md: var(--shadow-md);
+  --shadow-lg: var(--shadow-lg);
+  --shadow-xl: var(--shadow-xl);
+  --shadow-2xl: var(--shadow-2xl);
 }
 
 * {
@@ -2566,6 +2644,39 @@ body {
   color: var(--foreground);
   font-family: var(--font-sans);
 }
+
+/* Tailwind v4's Preflight no longer sets \`cursor: pointer\` on buttons \u2014
+   restore it so controls feel like the app's. */
+button:not(:disabled),
+[role="button"]:not([aria-disabled="true"]),
+label[for],
+summary {
+  cursor: pointer;
+}
+
+/* \u2500\u2500 Surface chrome \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   \`data-dw-surface\` is stamped on <html> before first paint by
+   PLATFORM_PREPAINT_SCRIPT (@dashai/sdk/platform). Chrome the Dashwise app
+   shell already provides \u2014 header, nav, logo, theme toggle, sign-out,
+   footer \u2014 goes in \`.dw-standalone-only\` and disappears when embedded.
+   CSS-only, so it is correct on the first frame and needs no JavaScript. */
+[data-dw-surface="embedded"] .dw-standalone-only {
+  display: none !important;
+}
+[data-dw-surface="standalone"] .dw-embedded-only {
+  display: none !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
 `;
 }
 function libUtilsTs() {
@@ -2608,7 +2719,9 @@ export function getPublicOrigin(request: Request): string {
 `;
 }
 function componentsUiButtonTsx() {
-  return `import * as React from "react";
+  return `"use client";
+
+import * as React from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 
@@ -2754,6 +2867,234 @@ export function ThemeProvider({
 }
 `;
 }
+function componentsPlatformThemeSyncTsx() {
+  return `"use client";
+
+import { useEffect } from "react";
+import { useTheme } from "next-themes";
+import { usePlatform } from "@dashai/sdk/platform";
+
+export function PlatformThemeSync() {
+  const { surface, theme: hostTheme } = usePlatform();
+  const { setTheme } = useTheme();
+
+  useEffect(() => {
+    // Standalone: the user's own choice (or \`system\`) is authoritative.
+    if (surface !== "embedded") return;
+    // null until the host answers \u2014 don't fight \`system\` in the meantime.
+    if (!hostTheme) return;
+    setTheme(hostTheme);
+  }, [surface, hostTheme, setTheme]);
+
+  return null;
+}
+`;
+}
+function componentsModuleShellTsx() {
+  return `import type { ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+interface ModuleShellProps {
+  /** The screen's name. Becomes the single <h1>. */
+  title: string;
+  /** One short line. Omit it rather than padding the screen with prose. */
+  description?: string;
+  /** The single primary action (one filled button). */
+  primaryAction?: ReactNode;
+  /** Up to three secondary actions; anything else belongs in a \u22EF menu. */
+  actions?: ReactNode;
+  /** Tabs, directly under the heading. Only with 2+ screens \u2014 never a sidebar. */
+  nav?: ReactNode;
+  /** Narrower container for forms and detail screens. */
+  width?: "default" | "narrow";
+  children: ReactNode;
+}
+
+/**
+ * Embedded, this renders content only \u2014 the Dashwise app shell already
+ * provides the header, sidebar, workspace switcher, user menu and theme
+ * toggle. Standalone, the slim header below appears.
+ *
+ * \`.dw-standalone-only\` is hidden by CSS when embedded (see globals.css), and
+ * the pre-paint script has already stamped <html>, so it is correct on the
+ * first painted frame with no layout shift.
+ */
+export function ModuleShell({
+  title,
+  description,
+  primaryAction,
+  actions,
+  nav,
+  width = "default",
+  children,
+}: ModuleShellProps) {
+  return (
+    <div className="min-h-0 w-full">
+      <header className="dw-standalone-only border-b border-border">
+        <div className="mx-auto flex h-14 max-w-6xl items-center justify-between px-4 md:px-6">
+          <span className="text-sm font-medium">{title}</span>
+          {/* Theme toggle + sign out belong here \u2014 standalone only. */}
+        </div>
+      </header>
+
+      <div
+        className={cn(
+          "mx-auto w-full p-4 md:p-6",
+          width === "narrow" ? "max-w-3xl" : "max-w-6xl",
+        )}
+      >
+        <div className="flex flex-wrap items-start justify-between gap-3">
+          <div className="min-w-0 space-y-1">
+            <h1 className="truncate text-xl font-semibold tracking-tight">
+              {title}
+            </h1>
+            {description && (
+              <p className="text-sm text-muted-foreground">{description}</p>
+            )}
+          </div>
+          {(primaryAction || actions) && (
+            <div className="flex shrink-0 items-center gap-2">
+              {actions}
+              {primaryAction}
+            </div>
+          )}
+        </div>
+
+        {nav && <div className="mt-4">{nav}</div>}
+
+        <main className="mt-6 space-y-6">{children}</main>
+      </div>
+    </div>
+  );
+}
+`;
+}
+function componentsStatesTsx() {
+  return `"use client";
+
+import type { ComponentType, ReactNode } from "react";
+import { AlertCircleIcon, InboxIcon, SearchXIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+/** Nothing created yet. Teaches what the screen is for + offers the action. */
+export function EmptyState({
+  icon: Icon = InboxIcon,
+  title,
+  description,
+  action,
+}: {
+  icon?: ComponentType<{ className?: string }>;
+  /** What this screen is for \u2014 never "No data". */
+  title: string;
+  description?: string;
+  /** An empty state without an action is a dead end. */
+  action?: ReactNode;
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center rounded-lg border border-dashed border-border px-6 py-12 text-center">
+      <Icon className="h-8 w-8 text-muted-foreground" aria-hidden />
+      <p className="mt-4 text-sm font-medium">{title}</p>
+      {description && (
+        <p className="mt-1 max-w-sm text-sm text-muted-foreground">{description}</p>
+      )}
+      {action && <div className="mt-4">{action}</div>}
+    </div>
+  );
+}
+
+/** The data exists, the filter hid it. Distinct from EmptyState on purpose. */
+export function NoResultsState({
+  title = "No matches",
+  description = "Try a different search, or clear the filters.",
+  onClear,
+  clearLabel = "Clear filters",
+}: {
+  title?: string;
+  description?: string;
+  onClear?: () => void;
+  clearLabel?: string;
+}) {
+  return (
+    <div className="flex flex-col items-center justify-center rounded-lg border border-dashed border-border px-6 py-12 text-center">
+      <SearchXIcon className="h-8 w-8 text-muted-foreground" aria-hidden />
+      <p className="mt-4 text-sm font-medium">{title}</p>
+      <p className="mt-1 max-w-sm text-sm text-muted-foreground">{description}</p>
+      {onClear && (
+        <Button variant="outline" size="sm" className="mt-4" onClick={onClear}>
+          {clearLabel}
+        </Button>
+      )}
+    </div>
+  );
+}
+
+/** What happened \xB7 what now. Never render a raw exception here. */
+export function ErrorState({
+  title = "That didn't load",
+  description = "We couldn't reach the server. Check your connection and try again.",
+  onRetry,
+  retryLabel = "Try again",
+}: {
+  title?: string;
+  description?: string;
+  onRetry?: () => void;
+  retryLabel?: string;
+}) {
+  return (
+    <div
+      role="alert"
+      className="flex flex-col items-center justify-center rounded-lg border border-border bg-card px-6 py-12 text-center"
+    >
+      <AlertCircleIcon className="h-8 w-8 text-destructive" aria-hidden />
+      <p className="mt-4 text-sm font-medium">{title}</p>
+      <p className="mt-1 max-w-sm text-sm text-muted-foreground">{description}</p>
+      {onRetry && (
+        <Button variant="outline" size="sm" className="mt-4" onClick={onRetry}>
+          {retryLabel}
+        </Button>
+      )}
+    </div>
+  );
+}
+
+export function Skeleton({ className }: { className?: string }) {
+  return (
+    <div className={cn("animate-pulse rounded-md bg-muted", className)} aria-hidden />
+  );
+}
+
+/**
+ * Loading, shaped like the content that's coming \u2014 a centred spinner tells the
+ * user nothing about what they're waiting for. Match \`rows\` and the row height
+ * to the real list or it will visibly jump on load.
+ */
+export function ListSkeleton({ rows = 5 }: { rows?: number }) {
+  return (
+    <div
+      className="space-y-2"
+      role="status"
+      aria-live="polite"
+      aria-busy="true"
+      aria-label="Loading"
+    >
+      {Array.from({ length: rows }).map((_, i) => (
+        <Skeleton key={i} className="h-12 w-full" />
+      ))}
+    </div>
+  );
+}
+
+/** Announced by screen readers without stealing focus (WCAG 4.1.3). */
+export function StatusMessage({ children }: { children: ReactNode }) {
+  return (
+    <p role="status" aria-live="polite" className="text-sm text-muted-foreground">
+      {children}
+    </p>
+  );
+}
+`;
+}
 function appErrorTsx() {
   return `"use client";
 
@@ -2812,7 +3153,7 @@ function seedMjs() {
   return `/**
  * seed.mjs \u2014 OPTIONAL seed/maintenance script template.
  *
- * Run it with the module's DashWise env injected (DASHWISE_API_URL +
+ * Run it with the module's Dashwise env injected (DASHWISE_API_URL +
  * DASHWISE_API_KEY resolved like \`dashwise query\`: explicit env \u2192
  * .env.local \u2192 the dwk_ key cached by your CLI login):
  *
@@ -2852,9 +3193,9 @@ import {
 
 const ERROR_MESSAGES: Record<string, string> = {
   access_denied:
-    "You declined the sign-in request. To use this module, you'll need to authorize it on the DashWise sign-in page.",
+    "You declined the sign-in request. To use this module, you'll need to authorize it on the Dashwise sign-in page.",
   server_error:
-    'The DashWise sign-in server returned an internal error. This is usually transient \u2014 try again in a moment.',
+    'The Dashwise sign-in server returned an internal error. This is usually transient \u2014 try again in a moment.',
   invalid_request:
     'The sign-in request was malformed. This is almost always a configuration bug \u2014 check that DASHWISE_API_URL and DASHWISE_API_KEY are set correctly and the callback origin is allowlisted (run "dashwise origins add <url>").',
   missing_code:
@@ -2884,7 +3225,7 @@ export default async function SignInErrorPage({ searchParams }: SignInErrorPageP
             <div className="flex-1">
               <CardTitle>Sign-in failed</CardTitle>
               <CardDescription>
-                The DashWise SSO flow couldn't complete.
+                The Dashwise SSO flow couldn't complete.
               </CardDescription>
             </div>
           </div>
@@ -2945,18 +3286,116 @@ function claudeMd(opts) {
   return `# CLAUDE.md \u2014 ${opts.name}
 
 Instructions for AI coding agents (Claude Code, Cursor, etc.) working
-in this DashWise module. Read this before making changes.
+in this Dashwise module. Read this before making changes.
 
 ## What this module is
 
-A DashWise ${isCustom ? "**custom Next.js** module (full app runtime, machine-class)" : "**hand-authored simple** module (isolate runtime)"} authored against \`@dashai/sdk\`.
+A Dashwise ${isCustom ? "**custom Next.js** module (full app runtime, machine-class)" : "**hand-authored simple** module (isolate runtime)"} authored against \`@dashai/sdk\`.
 Module slug: \`${opts.slug}\`.
 
-DashWise calls apps "modules". A module is a Next.js app + a
+Dashwise calls apps "modules". A module is a Next.js app + a
 manifest (\`module.json\`) declaring the tables it owns, modules it
-depends on, and actions it exposes. The DashWise backend hosts the
+depends on, and actions it exposes. The Dashwise backend hosts the
 data plane + auth; this module ships UI + business logic.
 
+## Embedded-first UI \u2014 read this before writing any component
+
+Your module normally renders as a **full-bleed iframe inside the Dashwise app
+shell**. Above it is the app header; to its left the app sidebar. The
+workspace switcher, user menu, theme toggle, global search and logo
+**already exist around you**. The single most common way an AI-built module
+gives itself away is rendering a second set of all that.
+
+### Never render (embedded)
+- a logo, wordmark or product name; a top nav, sidebar or hamburger
+- a theme toggle, user avatar, sign-out control, language switcher
+- a footer, "powered by", version string, marketing hero, landing page
+- a full-screen splash or a full-page centred spinner
+- \`min-h-screen\` / \`h-screen\` / \`100vh\` \u2014 you are not the screen
+- a second scroll container (the iframe scrolls; nested scrollbars are the
+  most recognisable "bolted on" tell). Sticky table headers are fine.
+
+### Always
+- exactly **one \`<h1>\`** per screen; page padding \`p-4 md:p-6\`; content in a
+  capped width. \`<ModuleShell>\` (components/module-shell.tsx) does all three
+- in-module nav only with 2+ screens, and then as **tabs under the \`<h1>\`**,
+  never a sidebar
+- real routes, not client-side tab state \u2014 the app deep-links into
+  \`/modules/<slug>/<your/path>\` and \`HostRouteSync\` keeps the address bar honest
+
+### Standalone
+Opened on its own subdomain (or \`dashwise dev\`) a slim header is fine. Put it
+in \`.dw-standalone-only\` \u2014 CSS-only, correct on the first painted frame \u2014 or
+use \`<StandaloneOnly>\` from \`@dashai/sdk/platform\` when something must not
+mount. **Chrome is OFF by default**: standalone must be proven, never assumed.
+
+### Tokens, never raw values
+If you are typing \`#\`, \`oklch(\`, \`rounded-[\` or \`shadow-[\` in a component,
+stop \u2014 there is a token, and hardcoding permanently opts that element out of
+the workspace's theme and branding.
+
+| Use | Token |
+|---|---|
+| primary action | \`bg-primary text-primary-foreground\` |
+| page / text | \`bg-background text-foreground\` |
+| surfaces | \`bg-card\`, \`border-border\` |
+| secondary text | \`text-muted-foreground\` |
+| hover surface | \`hover:bg-accent hover:text-accent-foreground\` |
+| focus ring | \`focus-visible:ring-ring\` |
+| danger / status | \`bg-destructive\`, \`text-success\`, \`text-warning\` |
+| select + status chips | the \`--option-*\` palette (\`bg-option-blue/10 text-option-blue\`) |
+| corners / elevation | \`rounded-md\`/\`rounded-lg\`, \`shadow-xs\`\u2026\`shadow-md\` |
+| type | inherit \`--font-sans\`; ids and code use \`font-mono\` |
+
+**Theme and branding arrive from the host.** \`PlatformProvider\` +
+\`PlatformThemeSync\` (already wired in \`app/layout.tsx\`) follow the app's
+light/dark choice and apply the workspace's brand colour to \`--primary\` /
+\`--brand-accent\`. Never hardcode a brand colour, and never override
+\`--accent\` \u2014 that's the neutral hover surface, and re-pointing it tints every
+hover state in the product. Dark mode is a gate: check both.
+
+### One job per screen \u2014 hard budgets
+| Budget | Cap |
+|---|---|
+| primary actions per screen | 1 |
+| secondary actions in the header | 3 (rest go in a \`\u22EF\` menu) |
+| table columns shown by default | 7 |
+| levels of visual hierarchy | 2 \u2014 no card-in-card-in-card |
+| accent colours on a screen | 1 (status colours don't count) |
+| nav items | 5 \u2014 more means the module does too much |
+
+If a screen needs two primary actions it is two screens. A tile nobody can
+click is decoration \u2014 delete it. Empty space is a feature.
+
+### States are mandatory, not polish
+Every data surface needs all of these \u2014 \`components/states.tsx\` has them:
+- **empty**: icon + one line of what this screen is for + the primary action.
+  Never a blank table, never "No data"
+- **filtered-empty**: distinct from empty, offers "Clear filters"
+- **loading**: a skeleton shaped like the content, not a centred spinner
+- **error**: what happened \xB7 why \xB7 what now, plus a retry. Never a raw
+  exception, never "Something went wrong" on its own
+- **success**: a toast after every create/update/delete
+
+### Accessibility is a gate (WCAG 2.1 AA)
+- every input has a real \`<label for>\` \u2014 a placeholder is not a label
+- **never \`outline-none\` without \`focus-visible:ring-2 ring-ring\`** \u2014 this is
+  the single most common failure
+- icon-only buttons need \`aria-label\`; \`Esc\` closes every dialog; focus
+  returns where it came from
+- errors are text (not colour alone), tied to the field via
+  \`aria-describedby\`, and say how to fix it
+- toasts and inline "Saved" live in an \`aria-live="polite"\` region
+- usable at 320px wide; tables get an \`overflow-x-auto\` wrapper
+- 4.5:1 contrast on body text; minimum 24\xD724px hit targets
+
+### Do not ship
+Gradient heroes \xB7 emoji as icons \xB7 \`alert()\`/\`confirm()\` \xB7 raw JSON or stack
+traces shown to a user \xB7 "Coming soon" cards \xB7 a table with no empty state \xB7
+unlabelled icon buttons \xB7 hardcoded English when the module is multilingual \xB7
+a viewer who can see buttons that then 403 \xB7 \`console.log\` left in shipped
+code \xB7 the \`dwk_\` key reachable from a client component.
+
 ## Spec-first, log-every-change
 
 This scaffold mirrors the dashwise-backend convention:
@@ -3004,6 +3443,33 @@ Allowed field types (18): \`text\`, \`long_text\`, \`number\`, \`boolean\`,
 \`link_row\`, \`file\`, \`multi_file\`, \`email\`, \`url\`,
 \`phone\`, \`formula\`, \`ai\`, \`uuid\`, \`jsonb\`.
 
+### \`human_edit\` \u2014 who may hand-edit each column
+
+Your owned tables are visible **and editable** in the Dashwise Data Hub, so a
+workspace Editor can hand-edit any column you create. You are the only party
+who knows which columns your logic depends on, and a wrong edit raises no
+error \u2014 the module just misbehaves later, somewhere else. Declare it per field
+(the scaffolded \`items\` table shows two of the three):
+
+| Value | Use for | Effect on a human edit |
+|---|---|---|
+| \`open\` | Data you never read \u2014 notes, descriptions, annotations. | Nothing. |
+| \`guarded\` | A human may legitimately set it, but you REACT to the value \u2014 dates you notify from, the assignee you route to, config you read each run. | Lands; the grid warns first. **Default.** |
+| \`locked\` | An invariant YOUR code maintains \u2014 state-machine status, external ids, ledger amounts, sync cursors. | Refused (\`MODULE_LOCKED_FIELD\`). \`human_edit_reason\` is REQUIRED and shown verbatim to the user. |
+
+\`\`\`jsonc
+{ "slug": "sync_cursor", "type": "datetime",
+  "human_edit": "locked",
+  "human_edit_reason": "the billing sync maintains this \u2014 change it on the invoice screen" }
+\`\`\`
+
+**Don't leave everything on the default.** A warning on every column trains
+people to click through warnings, which costs you the one column that mattered.
+Mark genuinely inert columns \`open\`.
+
+Only tables you OWN can be locked \u2014 a \`uses\` field def has no \`human_edit\` key
+at all, because that table belongs to the user, not to your module.
+
 ## Read + write data via the generated SDK
 
 The CLI's watcher regenerates typed clients into
@@ -3055,7 +3521,7 @@ granted key.
 ## Auth in dev mode
 
 \`dashwise dev\` registers a dev-mode SSO session with the backend so
-workspace members can sign into the locally-running module via DashWise
+workspace members can sign into the locally-running module via Dashwise
 SSO. The scaffold's \`/api/auth/sign-in\` route is a single path: it
 calls \`POST /api/module-api/sso/start-url\` with your \`dwk_\` key and
 follows the returned \`redirect_url\` \u2014 the same code runs in dev and in
@@ -3069,15 +3535,24 @@ in \`app/layout.tsx\`).
 ${isCustom ? `
 ## Design & home
 
-You OWN the UI \u2014 layout, components, and colors. Edit the theme tokens in
-\`app/globals.css\` freely (they're a starting point, not a mandate), reach
-for any Tailwind color (\`bg-indigo-600\`, \`text-emerald-500\`, \u2026), and pull
-in more shadcn blocks (see the README's "Adding UI blocks").
+You own the PRODUCT design \u2014 the screens, the flows, the components. You do
+not own the chrome or the palette: this module renders as a full-bleed iframe
+**inside** the Dashwise app shell, which already provides the header, sidebar,
+workspace switcher, user menu and theme toggle. So: no header of your own, no
+nav, no logo, no \`100vh\`, one \`<h1>\` per screen \u2014 see \`CLAUDE.md\` \u2192
+"Embedded-first UI" for the full contract, and use \`<ModuleShell>\` which
+encodes it.
+
+\`app/globals.css\` ships the app's REAL tokens (indigo \`--primary\`, Geist,
+\`--radius\`, the \`--option-*\` chip palette). Style with them and the module
+inherits the workspace's theme, dark mode and white-label branding for free;
+hardcode a hex and you permanently opt that element out. Pull in more shadcn
+blocks freely (see the README's "Adding UI blocks").
 
 The app's **home is \`app/page.tsx\`, served at \`/\`** \u2014 build the real app
 there. It's auth-gated: a platform user lands on it zero-click (the
 middleware's \`autoSignIn\` signs them in silently), and \`app/dashboard/page.tsx\`
-is just an extra example route. A manual "Sign in with DashWise" landing
+is just an extra example route. A manual "Sign in with Dashwise" landing
 page belongs ONLY to a \`public_access_allowed\` module that wants an
 anonymous entry point (re-add \`'/'\` to \`middleware.ts\` publicPaths + drop
 the home's session guard to build one).
@@ -3087,7 +3562,7 @@ the home's session guard to build one).
 Add \`export const dynamic = 'force-dynamic'\` to the top of ANY page that
 reads the session or data at render (calls \`getServerSession()\` or a
 \`dwk_\`-authenticated data call). Without it, \`next build\` statically
-prerenders the page with NO DashWise env vars, the SDK throws
+prerenders the page with NO Dashwise env vars, the SDK throws
 \`missing apiBaseUrl\`, and the platform's first publish fails with an
 opaque \`BUILD_FAILED\`. The scaffolded \`app/page.tsx\` + \`app/dashboard/page.tsx\`
 already have it \u2014 any new session-gated page you add needs it too.
@@ -3431,6 +3906,13 @@ async function moduleInitCommand(slugArg, options) {
       ["lib/utils.ts", libUtilsTs()],
       ["lib/request-origin.ts", libRequestOriginTs()],
       ["components/theme-provider.tsx", componentsThemeProviderTsx()],
+      // Embedded-first defaults: follow the Dashwise app's theme, and ship the
+      // page frame + the empty/loading/error states that a module needs to
+      // look finished. All three encode the CLAUDE.md "Embedded-first UI"
+      // contract so a module gets it right without being told.
+      ["components/platform-theme-sync.tsx", componentsPlatformThemeSyncTsx()],
+      ["components/module-shell.tsx", componentsModuleShellTsx()],
+      ["components/states.tsx", componentsStatesTsx()],
       ["components/ui/button.tsx", componentsUiButtonTsx()],
       ["components/ui/card.tsx", componentsUiCardTsx()],
       ["app/layout.tsx", appLayoutCustomTsx(scaffoldOpts)],
@@ -6209,6 +6691,14 @@ init_workspaces();
 function isDevInstallKind(kind) {
   return kind === "local" || kind === "sandbox";
 }
+function selectInstallsByKind(installs, moduleId) {
+  const all = installs.filter((row) => row.module_id === moduleId);
+  return {
+    production: all.find((row) => !isDevInstallKind(row.kind)),
+    dev: all.find((row) => isDevInstallKind(row.kind)),
+    all
+  };
+}
 function isRealRuntimeUrl(url) {
   return !!url && /^https:\/\//i.test(url);
 }
@@ -6306,9 +6796,12 @@ async function moduleInstallCommand(slugArg, options) {
     return 1;
   }
   let existing;
+  let devInstall;
   try {
     const installs = await listWorkspaceInstallations(workspace2.id, auth);
-    existing = installs.find((row2) => row2.module_id === mod.id);
+    const byKind = selectInstallsByKind(installs, mod.id);
+    existing = byKind.production;
+    devInstall = byKind.dev;
   } catch (err) {
     fail(
       `Could not read workspace installations: ${err.message}`
@@ -6318,18 +6811,35 @@ async function moduleInstallCommand(slugArg, options) {
   let isUpgrade = false;
   let devInstallToReplace;
   let confirmedViaPicker = false;
-  if (existing && isDevInstallKind(existing.kind)) {
+  if (!existing && devInstall) {
     const resolution = await resolveDevInstallCollision(
-      existing,
+      devInstall,
       slug,
       workspace2.slug,
       options
     );
     if (typeof resolution === "number") return resolution;
-    devInstallToReplace = existing;
-    confirmedViaPicker = resolution === "replace-confirmed";
-    existing = void 0;
+    if (resolution === "alongside") {
+      info(
+        `Keeping dev install #${devInstall.id} \u2014 installing production alongside it.`
+      );
+    } else {
+      devInstallToReplace = devInstall;
+      confirmedViaPicker = resolution === "replace-confirmed";
+    }
   } else if (existing) {
+    if (devInstall) {
+      if (options.replaceDevInstall) {
+        devInstallToReplace = devInstall;
+        info(
+          `Dev install #${devInstall.id} (${code(`kind=${devInstall.kind ?? "unknown"}`)}) will be DESTROYED as requested \u2014 its local-dev credentials are revoked. Re-provision later with ${code("dashwise module reset-dev-install")}.`
+        );
+      } else {
+        info(
+          `Dev install #${devInstall.id} (${code(`kind=${devInstall.kind ?? "unknown"}`)}) also exists and is left untouched \u2014 the two coexist.`
+        );
+      }
+    }
     isUpgrade = true;
     const installedVersion2 = existing.module_version?.version;
     if (installedVersion2 && installedVersion2 === targetVersion) {
@@ -6343,13 +6853,13 @@ async function moduleInstallCommand(slugArg, options) {
     }
   }
   if (!options.yes && process.stdout.isTTY && !confirmedViaPicker) {
-    const message = devInstallToReplace ? `Replace the dev install (revokes local-dev credentials) and install ${code(mod.slug)} ${code(`v${targetVersion}`)} into ${code(workspace2.slug)} as production?` : `${isUpgrade ? "Upgrade" : "Install"} ${code(mod.slug)} ${code(`v${targetVersion}`)} into workspace ${code(workspace2.slug)}?`;
+    const message = devInstallToReplace ? isUpgrade ? `Destroy the dev install (revokes local-dev credentials) and upgrade ${code(mod.slug)} to ${code(`v${targetVersion}`)} in ${code(workspace2.slug)}?` : `Replace the dev install (revokes local-dev credentials) and install ${code(mod.slug)} ${code(`v${targetVersion}`)} into ${code(workspace2.slug)} as production?` : `${isUpgrade ? "Upgrade" : "Install"} ${code(mod.slug)} ${code(`v${targetVersion}`)} into workspace ${code(workspace2.slug)}?`;
     const answer = await select({
       message,
       options: [
         {
           value: "go",
-          label: devInstallToReplace ? "Yes, replace the dev install + production-install" : isUpgrade ? "Yes, upgrade now" : "Yes, install now"
+          label: devInstallToReplace ? isUpgrade ? "Yes, destroy the dev install + upgrade" : "Yes, replace the dev install + production-install" : isUpgrade ? "Yes, upgrade now" : "Yes, install now"
         },
         { value: "cancel", label: "No, abort" }
       ],
@@ -6400,7 +6910,7 @@ async function moduleInstallCommand(slugArg, options) {
   let verified = false;
   try {
     const after = await listWorkspaceInstallations(workspace2.id, auth);
-    row = after.find((r) => r.module_id === mod.id);
+    row = selectInstallsByKind(after, mod.id).production;
     verified = row !== void 0;
   } catch {
   }
@@ -6479,19 +6989,26 @@ function resolveSlug(slugArg, dir) {
   }
 }
 async function resolveDevInstallCollision(existing, slug, workspaceSlug, options) {
+  if (options.keepDevInstall) {
+    return "alongside";
+  }
   if (existing.kind === "sandbox") {
     fail(
-      `Workspace ${code(workspaceSlug)} already has a ${code("kind=sandbox")} install of ${code(slug)} (id=${existing.id}), and only ONE install per (workspace, module) can exist.
+      `Workspace ${code(workspaceSlug)} already has a ${code("kind=sandbox")} install of ${code(slug)} (id=${existing.id}).
   A plain install would upgrade that row in place \u2014 but ${code("kind")} is immutable, so it would stay sandbox and hidden from the app sidebar.
-  The CLI can't destroy a sandbox install. Uninstall it from the dashboard first, or deploy with ${code("--workspace <other>")} to a separate workspace.`
+  The CLI can't DESTROY a sandbox install, so ${code("--replace-dev-install")} is unavailable here. Either:
+    - ${code("--keep-dev-install")} \u2014 install production alongside it (non-destructive; the two coexist on backends \u2265 2026-07-15),
+    - uninstall the sandbox install from the dashboard first, or
+    - ${code("--workspace <other>")} \u2014 deploy to a separate workspace.`
     );
     return 1;
   }
   const explanation = `Workspace ${code(workspaceSlug)} already has the DEV install of ${code(slug)} (kind=local, id=${existing.id}) created by ${code("dashwise init")}.
   Install ${code("kind")} is immutable: a plain install could land on that row's upgrade path \u2014 the runtime would provision, but it would STAY a dev install, hidden from the app sidebar.
   Options:
-    - ${code("--replace-dev-install")} \u2014 destroy the dev install, then fresh production install. Recommended when development is done. Local dev can be re-provisioned afterwards with ${code(`dashwise init ${slug} --workspace <ws>`)} on backends \u2265 2026-07-15 (dev + production installs coexist); on OLDER backends this is one-way \u2014 no re-provision anywhere once published (interim: a scoped key on the production install via ${code("api-keys create --install <id> --full-access")}, or duplicate the code under a NEW slug).
-    - ${code("--workspace <other>")} \u2014 deploy to a separate test/client workspace and keep this dev install. Recommended for ongoing development.`;
+    - ${code("--keep-dev-install")} \u2014 install production ALONGSIDE the dev install, keeping local dev working. Recommended while development is ongoing. Requires a backend \u2265 2026-07-15, where the live-install uniqueness is per KIND group, so one production and one dev install coexist.
+    - ${code("--replace-dev-install")} \u2014 destroy the dev install, then fresh production install. Local dev can be re-provisioned afterwards with ${code(`dashwise init ${slug} --workspace <ws>`)} on backends \u2265 2026-07-15; on OLDER backends this is one-way \u2014 no re-provision anywhere once published (interim: a scoped key on the production install via ${code("api-keys create --install <id> --full-access")}, or duplicate the code under a NEW slug).
+    - ${code("--workspace <other>")} \u2014 deploy to a separate test/client workspace and keep this dev install.`;
   if (options.replaceDevInstall) {
     info(explanation);
     return "replace";
@@ -6499,8 +7016,13 @@ async function resolveDevInstallCollision(existing, slug, workspaceSlug, options
   if (process.stdout.isTTY && !options.yes) {
     info(explanation);
     const answer = await select({
-      message: `Replace the dev install of ${code(slug)} in ${code(workspaceSlug)} with a production install? (revokes local-dev credentials)`,
+      message: `How should ${code(slug)} be installed into ${code(workspaceSlug)}?`,
       options: [
+        {
+          value: "alongside",
+          label: "Install alongside \u2014 keep the dev install and local dev working",
+          hint: "non-destructive; the two coexist (backend \u2265 2026-07-15)"
+        },
         {
           value: "replace",
           label: "Replace \u2014 destroy the dev install, then production-install",
@@ -6508,12 +7030,15 @@ async function resolveDevInstallCollision(existing, slug, workspaceSlug, options
         },
         { value: "cancel", label: "Cancel \u2014 I will deploy to another workspace" }
       ],
-      initialValue: "cancel"
+      // Non-destructive default: the safe choice should be one Enter away, and
+      // "keep both" is what the platform has supported since 2026-07-15.
+      initialValue: "alongside"
     });
     if (isCancel(answer) || answer === "cancel") {
       fail("Aborted. Nothing was changed.");
       return 130;
     }
+    if (answer === "alongside") return "alongside";
     return "replace-confirmed";
   }
   fail(explanation);
@@ -7122,9 +7647,12 @@ async function moduleStatusCommand(slugArg, options) {
     return 1;
   }
   let row;
+  let siblingDevInstall;
   try {
     const installs = await listWorkspaceInstallations(workspace2.id, auth);
-    row = installs.find((r) => r.module_id === mod.id);
+    const byKind = selectInstallsByKind(installs, mod.id);
+    row = byKind.production ?? byKind.dev;
+    siblingDevInstall = byKind.production ? byKind.dev : void 0;
   } catch (err) {
     fail(`Could not read workspace installations: ${err.message}`);
     return 1;
@@ -7165,7 +7693,10 @@ async function moduleStatusCommand(slugArg, options) {
         runtime_provisioned: runtimeProvisioned,
         runtime_url: row.runtime_url,
         public_url: row.public_url,
-        state
+        state,
+        // The coexisting dev install, so a script can see BOTH slots — the
+        // human output reports it and `--json` used to hide it.
+        dev_install: siblingDevInstall ? { id: siblingDevInstall.id, kind: siblingDevInstall.kind ?? null } : null
       })
     );
     return 0;
@@ -7186,9 +7717,14 @@ async function moduleStatusCommand(slugArg, options) {
   kv("Public URL:", row.public_url ?? dim("(none)"));
   kv("State:", stateLabel);
   out("");
-  if (row.kind === "local") {
+  if (siblingDevInstall) {
+    info(
+      `A ${code(`kind=${siblingDevInstall.kind ?? "unknown"}`)} dev install (#${siblingDevInstall.id}) also exists in this workspace and coexists with the production install above \u2014 that is the one ${code("dashwise dev")} talks to.`
+    );
+  }
+  if (isDevInstallKind(row.kind)) {
     info(
-      `This is the ${code("kind=local")} dev install \u2014 hidden from the app sidebar. A production deploy needs ${code("dashwise module install --replace-dev-install")} (or ${code("--workspace <other>")}).`
+      `This is the ${code(`kind=${row.kind ?? "unknown"}`)} dev install \u2014 hidden from the app sidebar. There is no production install in this workspace yet: ${code("dashwise module install --keep-dev-install")} adds one alongside (keeps local dev working), ${code("--replace-dev-install")} swaps this row for one, or ${code("--workspace <other>")} deploys elsewhere.`
     );
   } else if (state === "not_deployed") {
     info(
@@ -7248,7 +7784,8 @@ async function moduleUninstallCommand(slugArg, options) {
   let row;
   try {
     const installs = await listWorkspaceInstallations(workspace2.id, auth);
-    row = installs.find((r) => r.module_id === mod.id);
+    const byKind = selectInstallsByKind(installs, mod.id);
+    row = byKind.production ?? byKind.dev;
   } catch (err) {
     fail(`Could not read workspace installations: ${err.message}`);
     return 1;
@@ -7259,9 +7796,9 @@ async function moduleUninstallCommand(slugArg, options) {
     );
     return 1;
   }
-  if (row.kind === "local") {
+  if (isDevInstallKind(row.kind)) {
     fail(
-      `Install ${code(`#${row.id}`)} of ${code(mod.slug)} in ${code(workspace2.slug)} is the ${code("kind=local")} DEV install backing local development.
+      `Install ${code(`#${row.id}`)} of ${code(mod.slug)} in ${code(workspace2.slug)} is the ${code(`kind=${row.kind ?? "unknown"}`)} DEV install backing local development.
   Use ${code("dashwise module destroy-dev-install")} (or ${code("dashwise module reset-dev-install")} for a clean re-provision) instead \u2014 it also revokes the cached local-dev credentials.`
     );
     return 1;
@@ -9185,6 +9722,32 @@ init_api_client();
 init_config();
 init_manifest_io();
 init_output();
+var SMART_DASH_RE = /^[‒–—―−]/;
+function strayArgsError(stray, usage) {
+  if (!stray || stray.length === 0) return null;
+  const lines = [
+    `Unexpected argument${stray.length > 1 ? "s" : ""} ${stray.map((s) => `"${s}"`).join(", ")} \u2014 ${usage}`
+  ];
+  if (stray.some((s) => SMART_DASH_RE.test(s))) {
+    lines.push(
+      `A token starts with a typographic dash (\u2013 / \u2014) instead of ASCII "--". If this command was copy-pasted, the editor/chat likely rewrote the double hyphen \u2014 retype the flag by hand (e.g. ${code("--grant")}, ${code("--full-access")}).`
+    );
+  }
+  if (stray.some((s) => /^(module|datahub):/.test(s))) {
+    lines.push(
+      `Grant specs must be passed via the (repeatable) ${code("--grant")} flag, e.g. ${code("--grant module:employees:create,read")}.`
+    );
+  }
+  if (stray.some((s) => s.startsWith("--"))) {
+    lines.push(
+      `Tokens after a bare ${code("--")} separator are treated as plain arguments, not flags \u2014 remove the ${code("--")}.`
+    );
+  }
+  lines.push(
+    "Refusing to continue: silently ignoring these arguments is how grantless (deny-all) keys get minted by accident."
+  );
+  return lines.join("\n  ");
+}
 function loadContext4(opts) {
   const cfg = readConfig();
   if (!cfg) {
@@ -9250,6 +9813,14 @@ async function resolveInstallKind(ctx) {
   return void 0;
 }
 async function apiKeysListCommand(options) {
+  const strayErr = strayArgsError(
+    options.stray,
+    "`dashwise api-keys list` takes no positional arguments."
+  );
+  if (strayErr) {
+    fail(strayErr);
+    return 1;
+  }
   let ctx;
   try {
     ctx = loadContext4(options);
@@ -9300,6 +9871,20 @@ async function apiKeysListCommand(options) {
   return 0;
 }
 async function apiKeysCreateCommand(nameArg, options) {
+  if (nameArg !== void 0 && SMART_DASH_RE.test(nameArg)) {
+    fail(
+      `"${nameArg}" was read as the key NAME but looks like a flag typed with a typographic dash (\u2013 / \u2014) instead of ASCII "--". If this command was copy-pasted, the editor/chat likely rewrote the double hyphen \u2014 retype the flag by hand (e.g. ${code("--grant")}, ${code("--full-access")}).`
+    );
+    return 1;
+  }
+  const strayErr = strayArgsError(
+    options.stray,
+    "`dashwise api-keys create` takes a single <name>."
+  );
+  if (strayErr) {
+    fail(strayErr);
+    return 1;
+  }
   const name = nameArg ?? options.name;
   if (!name) {
     fail("Usage: `dashwise api-keys create <name>` (e.g. `dashwise api-keys create production`)");
@@ -9388,6 +9973,14 @@ async function apiKeysCreateCommand(nameArg, options) {
   return 0;
 }
 async function apiKeysRevokeCommand(keyIdArg, options) {
+  const strayErr = strayArgsError(
+    options.stray,
+    "`dashwise api-keys revoke` takes a single <key-id> \u2014 extra ids would be silently skipped."
+  );
+  if (strayErr) {
+    fail(strayErr);
+    return 1;
+  }
   if (!keyIdArg) {
     fail("Usage: `dashwise api-keys revoke <key-id>` \u2014 id from `dashwise api-keys list`");
     return 1;
@@ -11223,14 +11816,19 @@ apiKeysCmd.command("list").description(
   "--install <id>",
   "Target a specific installation id instead of the cached dev install (production installs included). Find ids via `dashwise module status <slug>`.",
   parseIntOption
-).option("--all", "Include revoked + expired keys in the output.").option("--json", "Emit JSON instead of the human-friendly table.").action(async (cmdOpts) => {
-  process.exitCode = await apiKeysListCommand({
-    ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
-    ...cmdOpts.install !== void 0 ? { install: cmdOpts.install } : {},
-    ...cmdOpts.all !== void 0 ? { all: cmdOpts.all } : {},
-    ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {}
-  });
-});
+).option("--all", "Include revoked + expired keys in the output.").option("--json", "Emit JSON instead of the human-friendly table.").action(
+  async (cmdOpts, cmd) => {
+    process.exitCode = await apiKeysListCommand({
+      ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
+      ...cmdOpts.install !== void 0 ? { install: cmdOpts.install } : {},
+      ...cmdOpts.all !== void 0 ? { all: cmdOpts.all } : {},
+      ...cmdOpts.json !== void 0 ? { json: cmdOpts.json } : {},
+      // Operands commander would otherwise SILENTLY drop (default
+      // allowExcessArguments) — the command hard-errors on them.
+      ...cmd.args.length > 0 ? { stray: cmd.args } : {}
+    });
+  }
+);
 apiKeysCmd.command("create [name]").description(
   "Mint a new API key. The plaintext key is displayed ONCE \u2014 save it then."
 ).option("--dir <path>", "Project root (default: current directory).").option(
@@ -11253,7 +11851,8 @@ apiKeysCmd.command("create [name]").description(
   "--raw-only",
   "Print only the plaintext key on stdout; chatter goes to stderr. Useful for shell capture: `KEY=$(dashwise api-keys create prod --raw-only)`"
 ).action(
-  async (nameArg, cmdOpts) => {
+  async (nameArg, cmdOpts, cmd) => {
+    const stray = cmd.args.slice(1);
     process.exitCode = await apiKeysCreateCommand(nameArg, {
       ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
       ...cmdOpts.install !== void 0 ? { install: cmdOpts.install } : {},
@@ -11261,7 +11860,8 @@ apiKeysCmd.command("create [name]").description(
       ...cmdOpts.grant !== void 0 && cmdOpts.grant.length > 0 ? { grant: cmdOpts.grant } : {},
       ...cmdOpts.fullAccess !== void 0 ? { fullAccess: cmdOpts.fullAccess } : {},
       ...cmdOpts.expires !== void 0 ? { expires: cmdOpts.expires } : {},
-      ...cmdOpts.rawOnly !== void 0 ? { rawOnly: cmdOpts.rawOnly } : {}
+      ...cmdOpts.rawOnly !== void 0 ? { rawOnly: cmdOpts.rawOnly } : {},
+      ...stray.length > 0 ? { stray } : {}
     });
   }
 );
@@ -11272,11 +11872,13 @@ apiKeysCmd.command("revoke [key-id]").description(
   "Target a specific installation id instead of the cached dev install (production installs included). Find ids via `dashwise module status <slug>`.",
   parseIntOption
 ).option("-y, --yes", "Skip the per-key confirmation message (for CI / scripts).").action(
-  async (keyIdArg, cmdOpts) => {
+  async (keyIdArg, cmdOpts, cmd) => {
+    const stray = cmd.args.slice(1);
     process.exitCode = await apiKeysRevokeCommand(keyIdArg, {
       ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
       ...cmdOpts.install !== void 0 ? { install: cmdOpts.install } : {},
-      ...cmdOpts.yes !== void 0 ? { yes: cmdOpts.yes } : {}
+      ...cmdOpts.yes !== void 0 ? { yes: cmdOpts.yes } : {},
+      ...stray.length > 0 ? { stray } : {}
     });
   }
 );
@@ -11364,16 +11966,20 @@ moduleCmd.command("publish").description("Pack the current directory + upload it
   }
 );
 moduleCmd.command("install [slug]").alias("deploy").description(
-  "Install (deploy) a published module into a workspace \u2014 provisions the runtime and prints the public URL. Upgrades/repairs an existing production install idempotently. Refuses to silently land on a dev install: use --replace-dev-install or --workspace <other>."
+  "Install (deploy) a published module into a workspace \u2014 provisions the runtime and prints the public URL. Upgrades/repairs an existing production install idempotently. When only a dev install exists it asks whether to install alongside it (--keep-dev-install) or replace it (--replace-dev-install), rather than silently landing on the dev row."
 ).option("--workspace <slug-or-id>", "Target workspace (default: cached module workspace, config default, or interactive picker).").option("--version <semver>", "Install a specific published version (default: latest).").option("--force", "Proceed even when the upgrade breaks consumer modules (UPGRADE_BREAKS_CONSUMERS).").option(
+  "--keep-dev-install",
+  "Install production ALONGSIDE the workspace's kind=local dev install, leaving local dev working. Non-destructive. Backends >= 2026-07-15 keep a separate live-install slot per kind group, so the two coexist."
+).option(
   "--replace-dev-install",
-  "Destroy the workspace's kind=local dev install first, then fresh production install. PERMANENTLY disables local dev for this module in this workspace (credentials revoked; a published module cannot be re-provisioned here) \u2014 continue development in a different workspace."
+  "Destroy the workspace's kind=local dev install first, then fresh production install. Revokes the cached local-dev credentials; on backends >= 2026-07-15 local dev can be re-provisioned afterwards (dashwise module reset-dev-install, or dashwise init <slug> --workspace <ws>) and will coexist with the production install. On OLDER backends this is one-way \u2014 prefer --keep-dev-install."
 ).option("--dir <path>", "Project root for the module.json slug lookup (default: current directory).").option("-y, --yes", "Skip the confirmation prompt (for CI / scripted use).").option("--json", "Emit the final result as machine-readable JSON.").action(
   async (slug, cmdOpts) => {
     process.exitCode = await moduleInstallCommand(slug, {
       ...cmdOpts.workspace !== void 0 ? { workspace: cmdOpts.workspace } : {},
       ...cmdOpts.version !== void 0 ? { version: cmdOpts.version } : {},
       ...cmdOpts.force !== void 0 ? { force: cmdOpts.force } : {},
+      ...cmdOpts.keepDevInstall !== void 0 ? { keepDevInstall: cmdOpts.keepDevInstall } : {},
       ...cmdOpts.replaceDevInstall !== void 0 ? { replaceDevInstall: cmdOpts.replaceDevInstall } : {},
       ...cmdOpts.dir !== void 0 ? { dir: cmdOpts.dir } : {},
       ...cmdOpts.yes !== void 0 ? { yes: cmdOpts.yes } : {},
@@ -11619,7 +12225,7 @@ fieldCmd.command("set-type <table-slug> <field-slug> <new-type>").description(
   }
 })();
 function getVersion() {
-  return "0.17.0";
+  return "0.18.1";
 }
 function parseIntOption(value) {
   const n = Number.parseInt(value, 10);