handoff-app 2.0.0-1 → 2.0.0-2

package/src/app/pages/foundations/icons/index.tsx

@@ -36,13 +36,13 @@ export const DisplayIcon: React.FC<{ icon: DisplayableAsset }> = ({ icon }) => {
 
   return (
     <div className="flex flex-col gap-2">
-      <Link href={`/foundations/icons/${icon.icon}`}>
+      <Link href={`/foundations/icons/library/${icon.icon}`}>
         <div className="flex flex-col items-center gap-6 rounded-lg border border-gray-100/80 bg-gray-100/80 py-12 transition-all hover:border-gray-300 hover:bg-gray-100 dark:border-gray-800 dark:bg-gray-900 dark:hover:border-gray-700 dark:hover:bg-gray-900">
           {/* Workspace/static: inline SVG body. Registry: the individual asset content URL. */}
           {icon.data ? <div dangerouslySetInnerHTML={{ __html: htmlData }} /> : <img className="o-icon h-6 w-6" src={icon.src} alt={icon.name} />}
         </div>
       </Link>
-      <Link href={`/foundations/icons/${icon.icon}`}>
+      <Link href={`/foundations/icons/library/${icon.icon}`}>
         <p className="font-mono text-[11px]">{icon.icon}</p>
       </Link>
     </div>

package/src/app/pages/foundations/icons/{[name] → library/[name]}/index.tsx

@@ -5,12 +5,12 @@ import { GetStaticProps } from 'next';
 import Link from 'next/link';
 import { useRouter } from 'next/router';
 import * as React from 'react';
-import Footer from '../../../../components/Footer';
-import Layout from '../../../../components/Layout/Main';
-import HeadersType from '../../../../components/Typography/Headers';
-import { buttonVariants } from '../../../../components/ui/button';
-import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens, isRegistryRuntime } from '../../../../components/util';
-import { useSingleAsset, type DisplayableAsset } from '../../../../components/util/useCollectionAssets';
+import Footer from '../../../../../components/Footer';
+import Layout from '../../../../../components/Layout/Main';
+import HeadersType from '../../../../../components/Typography/Headers';
+import { buttonVariants } from '../../../../../components/ui/button';
+import { AssetDocumentationProps, buildTimeAssets, fetchDocPageMarkdown, getClientRuntimeConfig, getTokens, isRegistryRuntime } from '../../../../../components/util';
+import { useSingleAsset, type DisplayableAsset } from '../../../../../components/util/useCollectionAssets';
 
 const DisplayIcon: React.FC<{ icon: DisplayableAsset }> = ({ icon }) => {
   const htmlData = React.useMemo(() => {

package/src/app-builder/build.ts

@@ -1,3 +1,4 @@
+import * as p from '@clack/prompts';
 import spawn from 'cross-spawn';
 import fs from 'fs-extra';
 import path from 'path';
@@ -7,7 +8,7 @@ import { buildPatterns } from '../pipeline/patterns';
 import processComponents from '../transformers/preview/component/builder';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
-import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryAdapter } from '../registry/db/adapter';
+import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
 import type { RuntimeMode } from '../types/config';
 import { Logger } from '../utils/logger';
@@ -104,6 +105,63 @@ const assertStaticBuildAllowed = (handoff: Handoff): void => {
   }
 };
 
+/**
+ * Run the Next.js production build while keeping its delayed output out of the successful CLI flow.
+ * Captured output is replayed only when the child fails so compiler diagnostics remain available.
+ */
+const runNextBuild = async (appPath: string, target: BuildTarget, errorLabel: string): Promise<void> => {
+  const spinner = p.spinner();
+  spinner.start('Building Next.js app...');
+
+  const stdout: Buffer[] = [];
+  const stderr: Buffer[] = [];
+
+  await new Promise<void>((resolve, reject) => {
+    const buildProcess = spawn('npx', ['next', 'build'], {
+      cwd: appPath,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        NODE_ENV: 'production',
+        HANDOFF_BUILD_TARGET: target,
+      },
+    });
+
+    buildProcess.stdout?.on('data', (chunk: Buffer) => stdout.push(Buffer.from(chunk)));
+    buildProcess.stderr?.on('data', (chunk: Buffer) => stderr.push(Buffer.from(chunk)));
+
+    let settled = false;
+
+    const fail = (message: string): void => {
+      if (settled) return;
+      settled = true;
+
+      spinner.stop('Next.js app build failed');
+      Logger.childProcessBuffer(Buffer.concat(stdout));
+      Logger.childProcessBuffer(Buffer.concat(stderr));
+      reject(new Error(message));
+    };
+
+    buildProcess.once('error', (error) => {
+      fail(`${errorLabel} failed to start\nSpawn error: ${error.message}`);
+    });
+
+    buildProcess.once('close', (code, signal) => {
+      if (settled) return;
+
+      if (code === 0) {
+        settled = true;
+        spinner.stop('Next.js app built successfully');
+        resolve();
+        return;
+      }
+
+      const reason = signal ? ` because it was terminated by signal ${signal}` : ` with exit code ${code}`;
+      fail(`${errorLabel} failed${reason}`);
+    });
+  });
+};
+
 /**
  * Output directory for the packaged registry app. Lives under the configurable sites output
  * directory (`sitesOutputDirectory`, default `out`) alongside the static target's `out/<projectId>`
@@ -198,7 +256,7 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
   // Resolved runtime mode + registry connection inputs (names only) baked into the Next bundle so the
   // deployed registry app resolves its mode/DB env-var name without any build-machine filesystem.
   const escapedRuntimeMode = escapeForSingleQuotedJsString(runtimeMode);
-  const escapedRegistryAdapter = escapeForSingleQuotedJsString(resolveRegistryAdapter(handoff.config));
+  const escapedRegistryDriver = escapeForSingleQuotedJsString(resolveRegistryDriver(handoff.config));
   const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString(resolveDatabaseUrlEnv(handoff.config));
   const escapedApiTokenEnv = escapeForSingleQuotedJsString(resolveApiTokenEnv(handoff.config));
   // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
@@ -216,7 +274,7 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
     '%HANDOFF_EXPORT_PATH%': escapedExportPath,
     '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
     '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
-    '%HANDOFF_REGISTRY_ADAPTER%': escapedRegistryAdapter,
+    '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
     '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
     '%HANDOFF_REGISTRY_API_TOKEN_ENV%': escapedApiTokenEnv,
     '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
@@ -283,26 +341,7 @@ const buildApp = async (
 
   // Build app. The static target drives Next's `output: 'export'` via HANDOFF_BUILD_TARGET so the
   // export gate is tied to the resolved target, not to NODE_ENV.
-  const buildResult = spawn.sync('npx', ['next', 'build'], {
-    cwd: appPath,
-    stdio: ['inherit', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      NODE_ENV: 'production',
-      HANDOFF_BUILD_TARGET: target,
-    },
-  });
-
-  Logger.childProcessBuffer(buildResult.stdout);
-  Logger.childProcessBuffer(buildResult.stderr);
-
-  if (buildResult.status !== 0) {
-    let errorMsg = `Next.js build failed with exit code ${buildResult.status}`;
-    if (buildResult.error) {
-      errorMsg += `\nSpawn error: ${buildResult.error.message}`;
-    }
-    throw new Error(errorMsg);
-  }
+  await runNextBuild(appPath, target, 'Next.js build');
 
   // Reproduce the docs read API (`/api/docs/*`) as route-shaped static files in the export output,
   // since `output: 'export'` disables the live API routes.
@@ -390,7 +429,7 @@ pipeline) before deploying new code:
 ${databaseUrlEnv}="postgres://…" handoff-app db:migrate
 \`\`\`
 
-\`db:migrate\` reads your project config + DB env vars, resolves the same database adapter the app was
+\`db:migrate\` reads your project config + DB env vars, resolves the same database driver the app was
 built with, and applies the package-owned migration set. It runs independently of \`build\` and of
 starting the server, so run it as a release/one-shot job.
 
@@ -437,14 +476,14 @@ containers, custom Node servers, and other non-Vercel hosts.
 
 /**
  * Resolve the set of npm packages the packaged registry app must be able to `require`/`import` at
- * runtime, given the configured database adapter. `next`/`react`/`react-dom` run the server and React
+ * runtime, given the configured database driver. `next`/`react`/`react-dom` run the server and React
  * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the driver
- * is adapter-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
+ * package is driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
  */
 const getRequiredRegistryRuntimeModules = (handoff: Handoff): string[] => {
   const base = ['next', 'react', 'react-dom', 'drizzle-orm'];
-  const adapter = resolveRegistryAdapter(handoff.config);
-  const driver = adapter === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
+  const driver = resolveRegistryDriver(handoff.config);
+  const driverModules = driver === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
   // Asset-storage SDKs the deployed registry must be able to load at request time. The pre-packaged
   // Vercel Blob adapter needs `@vercel/blob`; a custom adapter may declare its installed SDK
   // package(s) via `assetStorage.options.sdkModules` so the trace/assertion covers them.
@@ -457,7 +496,7 @@ const getRequiredRegistryRuntimeModules = (handoff: Handoff): string[] => {
   if (Array.isArray(sdkModules)) {
     storage.push(...sdkModules.filter((mod): mod is string => typeof mod === 'string'));
   }
-  return [...base, ...driver, ...storage];
+  return [...base, ...driverModules, ...storage];
 };
 
 /**
@@ -584,7 +623,7 @@ const assembleRegistryStandalone = async (
  *   - `vercel` → the Vercel Build Output API directory (`.vercel/output`) at the repo root: the
  *     traced bundle wrapped as a Node function plus CDN static assets and a route table.
  *
- * Mode is forced to `registry`; the database adapter is honored from config (single-sourced so build
+ * Mode is forced to `registry`; the database driver is honored from config (single-sourced so build
  * and `db:migrate` never diverge). No connection-string value is ever baked — only env-var *names*.
  */
 const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = 'standalone'): Promise<void> => {
@@ -597,16 +636,16 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
     Logger.info(`Source runtime.mode is "${sourceMode}"; forcing "registry" mode in the packaged registry app.`);
   }
 
-  // The adapter stays single-sourced from config (never flipped by the package flag), so build and
+  // The driver stays single-sourced from config (never flipped by the package flag), so build and
   // `db:migrate` always resolve the same one. `pg` uses long-lived TCP connections that pool poorly on
   // serverless; warn (non-fatally) so the operator points DATABASE_URL at a pooled endpoint or selects
-  // the Neon adapter. The connection-string value is not available at build time, so this cannot be
+  // the Neon driver. The connection-string value is not available at build time, so this cannot be
   // validated — it is guidance only and never fails the build.
-  if (buildPackage === 'vercel' && resolveRegistryAdapter(handoff.config) === 'pg') {
+  if (buildPackage === 'vercel' && resolveRegistryDriver(handoff.config) === 'pg') {
     Logger.warn(
-      'Registry Vercel build uses the "pg" adapter (standard TCP connections), which pools poorly on ' +
+      'Registry Vercel build uses the "pg" driver (standard TCP connections), which pools poorly on ' +
         'serverless and can exhaust the database connection limit. Point DATABASE_URL at a pooled endpoint ' +
-        '(PgBouncer / transaction pooling), or set runtime.registry.database.adapter: "neon" for a ' +
+        '(PgBouncer / transaction pooling), or set runtime.registry.database.driver: "neon" for a ' +
         'serverless-native HTTP/WebSocket driver. The build will continue.'
     );
   }
@@ -632,26 +671,7 @@ const buildRegistryApp = async (handoff: Handoff, buildPackage: BuildPackage = '
 
   // Build the dynamic app. `output: 'standalone'` (driven by HANDOFF_BUILD_TARGET) traces the runtime
   // and the selected Postgres/Neon driver into a self-contained bundle — never a static export.
-  const buildResult = spawn.sync('npx', ['next', 'build'], {
-    cwd: appPath,
-    stdio: ['inherit', 'pipe', 'pipe'],
-    env: {
-      ...process.env,
-      NODE_ENV: 'production',
-      HANDOFF_BUILD_TARGET: 'registry',
-    },
-  });
-
-  Logger.childProcessBuffer(buildResult.stdout);
-  Logger.childProcessBuffer(buildResult.stderr);
-
-  if (buildResult.status !== 0) {
-    let errorMsg = `Registry app build failed with exit code ${buildResult.status}`;
-    if (buildResult.error) {
-      errorMsg += `\nSpawn error: ${buildResult.error.message}`;
-    }
-    throw new Error(errorMsg);
-  }
+  await runNextBuild(appPath, 'registry', 'Registry app build');
 
   // Assemble the deployable package. Standalone tracing is rooted at the package (modulePath), so the
   // app's traced files land under `<relAppDir>` inside the standalone tree; static assets and public

package/src/app-builder/client-config.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import Handoff from '..';
 import { getClientConfig } from '../config';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
-import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryAdapter } from '../registry/db/adapter';
+import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
 import type { Config, RuntimeMode } from '../types/config';
 import { getAppPath } from './paths';
 
@@ -48,7 +48,7 @@ export const generateTokensApi = async (handoff: Handoff) => {
  * Build the server-only runtime config consumed by the docs read API.
  *
  * The browser-facing `client.config.json` carries only the resolved mode; the server additionally
- * needs the registry connection *inputs* (selected adapter + the *name* of the database-URL env
+ * needs the registry connection *inputs* (selected driver + the *name* of the database-URL env
  * var) to back the registry-mode docs read API. These are non-secret — the connection-string value
  * itself is never persisted, only resolved from the env var at request time.
  */
@@ -57,7 +57,7 @@ const buildServerRuntimeConfig = (config: Config, modeOverride?: RuntimeMode) =>
   return {
     mode: modeOverride ?? config?.runtime?.mode ?? 'workspace',
     registry: {
-      adapter: resolveRegistryAdapter(config),
+      driver: resolveRegistryDriver(config),
       databaseUrlEnv: resolveDatabaseUrlEnv(config),
       apiTokenEnv: resolveApiTokenEnv(config),
     },

package/src/app-builder/paths.ts

@@ -42,13 +42,11 @@ const mirrorDirectory = async (sourcePath: string, destinationPath: string): Pro
 };
 
 /**
- * Stage the fetch-produced asset download bundles (`exported/<id>/{collection}.zip`) into the app
- * public root, where the docs read API's workspace asset store serves them at
- * `/api/docs/assets/{collection}/{collection}.zip` (the canonical download URL). `fetch` writes these
- * bundles, but a plain `build`/`start` cleans and re-stages `.handoff` without carrying them, so the
- * download links would 404 until a fetch happened to run. Copying the committed export bundles here
- * makes the route resolve deterministically in workspace dev and static builds. Absent bundles (a
- * project with no logos/icons) are skipped.
+ * Copy the fetch-produced asset bundles (`exported/<id>/{collection}.zip`) into the app's public
+ * root, where the docs read API serves them at `/api/docs/assets/{collection}/{collection}.zip`.
+ * `fetch` writes these bundles, but `build`/`start` cleans and re-stages `.handoff` without them, so
+ * the download links 404 until the next fetch. Copying them here keeps the route working in workspace
+ * dev and static builds. Projects with no logos/icons have no bundles, so those are skipped.
  */
 const stageAssetDownloadBundles = async (handoff: Handoff, destinationPublicPath: string): Promise<void> => {
   const bundles: Array<{ src: string; name: string }> = [
@@ -85,7 +83,7 @@ export const syncPublicFiles = async (handoff: Handoff): Promise<void> => {
     await mirrorDirectory(sourceApiPath, destinationApiPath);
   }
 
-  // Stage the asset download bundles regardless of whether the workspace has a `public/` dir — they
-  // come from the fetch output, not the workspace public tree.
+  // Stage the asset bundles even when the workspace has no `public/` dir; they come from the fetch
+  // output, not the workspace public tree.
   await stageAssetDownloadBundles(handoff, destinationPublicPath);
 };

package/src/app-builder/static-export.ts

@@ -217,12 +217,12 @@ export const materializeDocsReadModel = async (handoff: Handoff, outDir: string)
 }
 
 /**
- * Materialize the whole-collection asset download bundles at the canonical asset route
- * (`api/docs/assets/{collection}/{collection}.zip`) — the same URL the docs read API serves in
- * registry mode, so the "Download" links resolve identically on a static host. The bundles come from
- * the fetch output (`exported/<id>/{collection}.zip`); `next build` never re-creates them, and the
- * fetch-time copy into the app `public/` is wiped by the build's clean+restage, so they are copied
- * here. Absent bundles (a project with no logos/icons) are skipped, not an error.
+ * Write the whole-collection asset bundles to the asset route
+ * (`api/docs/assets/{collection}/{collection}.zip`), the same URL the docs read API serves in
+ * registry mode, so the "Download" links work identically on a static host. The bundles come from the
+ * fetch output (`exported/<id>/{collection}.zip`); `next build` never re-creates them and the
+ * fetch-time copy into `public/` is wiped by the build's clean+restage, so we copy them here again.
+ * Projects with no logos/icons have no bundles, so those are skipped rather than treated as an error.
  */
 const materializeAssetDownloads = async (handoff: Handoff, docsRoot: string): Promise<void> => {
   const bundles: Array<{ collection: string; src: string }> = [

package/src/app-builder/vercel-output.ts

@@ -66,7 +66,7 @@ export const writeStaticVercelOutput = async (handoff: Handoff, exportDir: strin
 };
 
 /**
- * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` adapter
+ * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` driver
  * (and the Neon serverless driver in its Node fallback) need the Node.js runtime, not the edge
  * runtime — this is the required baseline. Vercel resolves the patch
  * version within this major; pinning the major keeps the artifact stable.
@@ -98,7 +98,7 @@ const MUTABLE_REGISTRY_PAGE_SRC_ROUTE = '/[...slug]';
  * data routes resolve the same way they do under the standalone server. `minimalMode:false` keeps
  * the function doing full in-process routing (the catch-all route forwards everything here).
  *
- * Runtime mode, adapter, and the DB env-var *name* are already baked into the resolved config the
+ * Runtime mode, driver, and the DB env-var *name* are already baked into the resolved config the
  * standalone build wrote to `.next/required-server-files.json`; the connection-string value is still
  * read from the named env var at request time, never baked.
  */

package/src/artifacts/url.ts

@@ -20,7 +20,7 @@ export const ARTIFACTS_ROUTE_SEGMENT = 'api/docs/artifacts';
 /** Route prefix for docs read API metadata (`.json`) reads. */
 export const DOCS_ROUTE_SEGMENT = 'api/docs';
 
-/** Canonical route prefix all asset content URLs are served under (mode-independent). */
+/** Route prefix all asset content URLs are served under, regardless of runtime mode. */
 export const ASSETS_ROUTE_SEGMENT = 'api/docs/assets';
 
 /**
@@ -93,11 +93,11 @@ export const buildPatternDetailUrl = (id: string, basePath?: string | null): str
   `${normalizeBasePath(basePath)}/${DOCS_ROUTE_SEGMENT}/patterns/${encodeURIComponent(id)}.json`;
 
 /**
- * Build the canonical, basePath-aware content URL for one asset within a collection
+ * Build the basePath-aware content URL for a single asset in a collection
  * (`{basePath}/api/docs/assets/{collection}/{logicalPath}`). This is the same route the docs read API
  * serves in every runtime mode: from the database in registry mode, and from statically materialized
- * files in a static export. Each segment is individually encoded and traversal segments are rejected,
- * mirroring {@link buildArtifactUrl}.
+ * files in a static export. Each segment is encoded on its own and traversal segments are rejected,
+ * matching {@link buildArtifactUrl}.
  *
  * @throws If the collection or logical path has no usable segments, or contains a `.`/`..` segment.
  */
@@ -114,9 +114,9 @@ export const buildAssetUrl = (collection: string, logicalPath: string, basePath?
 };
 
 /**
- * Build the canonical download URL for a collection's whole-collection zip bundle
- * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`) — the default target for the docs
- * "Download" links, overridable via `assets_zip_links`.
+ * Build the download URL for a collection's zip bundle
+ * (`{basePath}/api/docs/assets/{collection}/{collection}.zip`). This is the default target for the
+ * docs "Download" links and can be overridden via `assets_zip_links`.
  */
 export const buildAssetDownloadUrl = (collection: string, basePath?: string | null): string =>
   buildAssetUrl(collection, `${collection}.zip`, basePath);

package/src/cli/create.ts

@@ -23,6 +23,8 @@ interface CreateOptions {
   figmaAccessToken: string;
   languagePreference: 'typescript' | 'javascript';
   includeExamples: boolean;
+  includeVercel: boolean;
+  vercelBuildCommand: string;
   [key: string]: string | boolean; // Allow dynamic access for template replacement
 }
 
@@ -67,7 +69,8 @@ interface TemplateConfig {
  */
 const getMandatoryTemplates = (
   includeExamples: boolean,
-  languagePreference: 'typescript' | 'javascript'
+  languagePreference: 'typescript' | 'javascript',
+  includeVercel: boolean
 ): TemplateConfig[] => {
   const configFormat = languagePreference;
   const configTemplateBaseName = includeExamples ? 'handoff.config.with-examples' : 'handoff.config';
@@ -89,6 +92,10 @@ const getMandatoryTemplates = (
     templates.push({ source: 'tsconfig.json.tpl', destination: 'tsconfig.json' });
   }
 
+  if (includeVercel) {
+    templates.push({ source: 'vercel.json.tpl', destination: 'vercel.json' });
+  }
+
   return templates;
 };
 
@@ -118,7 +125,8 @@ const renderTemplate = (content: string, data: CreateOptions): string => {
 };
 
 const getDependenciesToInstall = (options: CreateOptions): { dependencies: string[]; devDependencies: string[] } => {
-  const dependencies = ['handoff-app@latest'];
+  // TODO: switch back to `handoff-app@latest` before the 2.0 stable release.
+  const dependencies = ['handoff-app@next'];
   const devDependencies: string[] = [];
 
   if (options.includeExamples) {
@@ -263,6 +271,51 @@ const create = async (): Promise<void> => {
 
     const languagePreference = languagePreferenceSelection as 'typescript' | 'javascript';
 
+    const includeVercelSelection = await p.confirm({
+      message: 'Add a Vercel deployment config (vercel.json)?',
+      initialValue: true,
+    });
+
+    if (p.isCancel(includeVercelSelection)) {
+      p.cancel('Project creation cancelled.');
+      process.exit(0);
+    }
+
+    const includeVercel = includeVercelSelection as boolean;
+
+    // When a Vercel config is scaffolded, choose which deployment its build command produces. Both
+    // package to `.vercel/output`; they differ in what is served. Registry is the recommended,
+    // pre-selected option; static stays available as the simplest deploy.
+    let vercelBuildCommand = 'npm run build -- --target registry --package vercel';
+    if (includeVercel) {
+      const vercelDeploymentSelection = await p.select({
+        message: 'Which deployment should Vercel build?',
+        options: [
+          {
+            value: 'registry',
+            label: 'Registry (dynamic)',
+            hint: 'Live, database-backed app (needs a Postgres DATABASE_URL). The more capable, actively evolving option — recommended for a shared design system.',
+          },
+          {
+            value: 'static',
+            label: 'Static site',
+            hint: 'Prebuilt snapshot served as plain files. The simplest to deploy and run.',
+          },
+        ],
+        initialValue: 'registry',
+      });
+
+      if (p.isCancel(vercelDeploymentSelection)) {
+        p.cancel('Project creation cancelled.');
+        process.exit(0);
+      }
+
+      vercelBuildCommand =
+        vercelDeploymentSelection === 'registry'
+          ? 'npm run build -- --target registry --package vercel'
+          : 'npm run build -- --target static --package vercel';
+    }
+
     // Get Figma project ID
     p.log.step(chalk.blue('Figma Configuration'));
     const figmaProjectId = await p.text({
@@ -295,6 +348,8 @@ const create = async (): Promise<void> => {
       figmaAccessToken: ((figmaAccessToken as string) || '').trim(),
       languagePreference,
       includeExamples,
+      includeVercel,
+      vercelBuildCommand,
     };
 
     // Create files
@@ -309,7 +364,7 @@ const create = async (): Promise<void> => {
 
     // Combine mandatory templates with example templates based on user choice
     const templates = [
-      ...getMandatoryTemplates(includeExamples, languagePreference),
+      ...getMandatoryTemplates(includeExamples, languagePreference, includeVercel),
       ...(includeExamples ? getExampleTemplates(languagePreference) : []),
     ];
 

package/src/commands/checkout/index.ts

@@ -2,20 +2,18 @@ import { CommandModule } from 'yargs';
 import Handoff from '../../';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
-import { getSharedOptions } from '../utils';
-
-/** Entity kinds checkout-able from a connected workspace. */
-const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'] as const;
+import { ENTITY_WIRE_KIND, getSharedOptions, REGISTRY_ENTITY_KINDS, RegistryEntityKind } from '../utils';
 
 export interface CheckoutArgs extends SharedArgs {
-  type: (typeof ENTITY_KINDS)[number];
+  type: RegistryEntityKind;
   id?: string;
 }
 
 /**
- * `handoff-app checkout <component|pattern|page> <id>` — pull an entity from the connected registry
- * into this workspace: writes its source files in standard authoring form and synthesizes a local
- * declaration.
+ * `handoff-app checkout <components|patterns|pages> [id]` pulls entities from the connected registry
+ * into this workspace, writing their source files in standard authoring form and synthesizing local
+ * declarations. Pass an `id` to pull that one entity, or omit it to pull every published entity of
+ * that kind.
  *
  * `handoff-app checkout tokens [setId]` — pull every published token set (or only the named set) into
  * this workspace: reconstruct `tokens.json` and restore the generated token files.
@@ -28,16 +26,16 @@ export interface CheckoutArgs extends SharedArgs {
  */
 const command: CommandModule<{}, CheckoutArgs> = {
   command: 'checkout <type> [id]',
-  describe: 'Pull a component, pattern, page, design tokens, or assets from the connected registry into this workspace',
+  describe: 'Pull components, patterns, pages, design tokens, or assets from the connected registry into this workspace',
   builder: (yargs) => {
     return getSharedOptions(yargs)
       .positional('type', {
         describe: 'The kind of entity to checkout',
-        choices: ENTITY_KINDS,
+        choices: REGISTRY_ENTITY_KINDS,
         type: 'string',
       })
       .positional('id', {
-        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to checkout all of that kind',
         type: 'string',
       });
   },
@@ -52,10 +50,7 @@ const command: CommandModule<{}, CheckoutArgs> = {
         await handoff.checkoutAssets(args.id);
         return;
       }
-      if (!args.id) {
-        throw new Error(`An id is required to checkout a ${args.type} (e.g. "handoff-app checkout ${args.type} <id>").`);
-      }
-      await handoff.checkout(args.type, args.id);
+      await handoff.checkout(ENTITY_WIRE_KIND[args.type], args.id);
     } catch (error) {
       Logger.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;

package/src/commands/publish/index.ts

@@ -2,19 +2,18 @@ import { CommandModule } from 'yargs';
 import Handoff from '../../';
 import { Logger } from '../../utils/logger';
 import { SharedArgs } from '../types';
-import { getSharedOptions } from '../utils';
-
-/** Entity kinds publishable from a connected workspace. */
-const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'] as const;
+import { ENTITY_WIRE_KIND, getSharedOptions, REGISTRY_ENTITY_KINDS, RegistryEntityKind } from '../utils';
 
 export interface PublishArgs extends SharedArgs {
-  type: (typeof ENTITY_KINDS)[number];
+  type: RegistryEntityKind;
   id?: string;
 }
 
 /**
- * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
- * selected entity to the connected registry.
+ * `handoff-app publish <components|patterns|pages> [id]` runs a fresh local build and uploads to the
+ * connected registry. Pass an `id` to build and upload that one entity, or omit it to build the kind
+ * once and upload every declared entity, skipping any whose content already matches the registry
+ * (pass `--force` to re-upload everything).
  *
  * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
  * only the named set (`foundation/colors`, `component/button`).
@@ -25,16 +24,16 @@ export interface PublishArgs extends SharedArgs {
  */
 const command: CommandModule<{}, PublishArgs> = {
   command: 'publish <type> [id]',
-  describe: 'Build and publish a component, pattern, page, design tokens, or assets to the connected registry',
+  describe: 'Build and publish components, patterns, pages, design tokens, or assets to the connected registry',
   builder: (yargs) => {
     return getSharedOptions(yargs)
       .positional('type', {
         describe: 'The kind of entity to publish',
-        choices: ENTITY_KINDS,
+        choices: REGISTRY_ENTITY_KINDS,
         type: 'string',
       })
       .positional('id', {
-        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+        describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to publish all of that kind',
         type: 'string',
       });
   },
@@ -49,10 +48,7 @@ const command: CommandModule<{}, PublishArgs> = {
         await handoff.publishAssets(args.id);
         return;
       }
-      if (!args.id) {
-        throw new Error(`An id is required to publish a ${args.type} (e.g. "handoff-app publish ${args.type} <id>").`);
-      }
-      await handoff.publish(args.type, args.id);
+      await handoff.publish(ENTITY_WIRE_KIND[args.type], args.id);
     } catch (error) {
       Logger.error(error instanceof Error ? error.message : String(error));
       process.exitCode = 1;

package/src/commands/utils.ts

@@ -1,4 +1,16 @@
 import { Argv } from 'yargs';
+import type { TransferEntityKind } from '../registry/transfer';
+
+/** Plural entity kinds accepted by the `publish`/`checkout` commands. */
+export const REGISTRY_ENTITY_KINDS = ['components', 'patterns', 'pages', 'tokens', 'assets'] as const;
+export type RegistryEntityKind = (typeof REGISTRY_ENTITY_KINDS)[number];
+
+/** Map the plural CLI kind to the singular wire kind used by entity publish/checkout. */
+export const ENTITY_WIRE_KIND: Record<'components' | 'patterns' | 'pages', TransferEntityKind> = {
+  components: 'component',
+  patterns: 'pattern',
+  pages: 'page',
+};
 
 export const getSharedOptions = (yargs: Argv) => {
   return yargs.options({