handoff-app 2.0.0-1 → 2.0.0-2

package/src/index.ts

@@ -138,26 +138,40 @@ class Handoff {
   }
 
   /**
-   * Publish a single component, pattern, or page from this connected workspace to the configured
-   * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
-   * upload their record and markdown source because they render at runtime. The publish module is
-   * loaded lazily so the registry client and build code never enter the docs app bundle.
+   * Publish components, patterns, or pages from this connected workspace to the configured remote
+   * registry. With `id` it publishes that one entity after a targeted build; without `id` it builds
+   * the kind once and publishes every declared entity, skipping ones whose content is unchanged on
+   * the registry (`--force` re-uploads all). Pages upload their record and markdown source because
+   * they render at runtime. The publish module is loaded lazily so the registry client and build code
+   * never enter the docs app bundle.
    */
-  async publish(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff> {
+  async publish(kind: 'component' | 'pattern' | 'page', id?: string): Promise<Handoff> {
     this.preRunner();
-    const { publishEntity } = await import('./registry/publish');
-    await publishEntity(this, kind, id);
+    if (id) {
+      const { publishEntity } = await import('./registry/publish');
+      await publishEntity(this, kind, id);
+    } else {
+      const { publishEntities } = await import('./registry/publish');
+      await publishEntities(this, kind);
+    }
     return this;
   }
 
   /**
-   * Checkout a single component, pattern, or page from the connected remote registry. The checkout
-   * module is loaded lazily so the registry client never enters the docs app bundle.
+   * Checkout components, patterns, or pages from the connected remote registry into this workspace.
+   * With `id` it checks out that one entity; without `id` it checks out every published entity of the
+   * kind. Overwriting existing local files requires `--force` or an interactive confirmation. The
+   * checkout module is loaded lazily so the registry client never enters the docs app bundle.
    */
-  async checkout(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff> {
+  async checkout(kind: 'component' | 'pattern' | 'page', id?: string): Promise<Handoff> {
     this.preRunner();
-    const { checkoutEntity } = await import('./registry/checkout');
-    await checkoutEntity(this, kind, id);
+    if (id) {
+      const { checkoutEntity } = await import('./registry/checkout');
+      await checkoutEntity(this, kind, id);
+    } else {
+      const { checkoutEntities } = await import('./registry/checkout');
+      await checkoutEntities(this, kind);
+    }
     return this;
   }
 

package/src/registry/asset-storage/resolve.ts

@@ -3,7 +3,7 @@
  *
  * `runtime.registry.assetStorage` selects the active provider for **new** uploads: the built-in
  * `database` inline default, the pre-packaged `vercel-blob` adapter, or a `custom` module. Mirrors
- * {@link import('../db/adapter')}: only provider selection, module location, non-secret options, and
+ * {@link import('../db/driver')}: only provider selection, module location, non-secret options, and
  * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
  */
 

package/src/registry/checkout/index.ts

@@ -1,7 +1,7 @@
 /**
  * Connected-workspace checkout orchestration.
  *
- * `checkout <component|pattern> <id>` reads a normalized registry record and its registry-safe
+ * `checkout <components|patterns> <id>` reads a normalized registry record and its registry-safe
  * source files from the connected registry through the shared registry client, then writes them
  * into the local workspace in standard authoring form. The local **declaration is synthesized
  * locally** in the configured `runtime.workspace.declarationFormat` — declarations are never read
@@ -20,7 +20,7 @@ import { resolveComponentDeclaration } from '../../config/runtime';
 import Handoff from '../../index';
 import type { DeclarationFormat } from '../../types/config';
 import { Logger } from '../../utils/logger';
-import { createRegistryClient, RegistryClientError } from '../client';
+import { createRegistryClient, type RegistryClient, RegistryClientError } from '../client';
 import { resolveRegistryConnection } from '../connection';
 import { isSafePathSegment, isSafeRelativePath, resolvePathWithin } from '../path';
 import type { CheckoutPayload, TransferEntityKind, TransferFile } from '../transfer';
@@ -530,26 +530,31 @@ const checkoutPage = async (handoff: Handoff, id: string, payload: CheckoutPaylo
 };
 
 /**
- * Checkout a single component or pattern from a connected workspace: precondition checks → fetch the
- * normalized record + source files → resolve the local target → explicit-overwrite guard → write
- * source files and synthesize the local declaration. Throws {@link CheckoutError} with actionable
- * messaging on any precondition or fetch failure.
+ * Checkout one entity through an already-resolved client: precondition checks → fetch the normalized
+ * record + source files → resolve the local target → explicit-overwrite guard → write source files
+ * and synthesize the local declaration. Shared by the single-id and bulk entry points so both behave
+ * identically. Throws {@link CheckoutError} with actionable messaging on any precondition or fetch
+ * failure.
  */
-export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
+const checkoutSingle = async (
+  handoff: Handoff,
+  kind: TransferEntityKind,
+  id: string,
+  client: RegistryClient,
+  registryUrl: string
+): Promise<void> => {
   const validId = kind === 'page' ? isSafeRelativePath(id) : isSafePathSegment(id);
   if (!validId) {
     throw new CheckoutError(`Cannot checkout ${kind} with unsafe id "${id}".`);
   }
-  const connection = resolveConnectionOrThrow(handoff);
 
-  Logger.info(`Fetching ${kind} "${id}" from ${connection.url}…`);
-  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  Logger.info(`Fetching ${kind} "${id}" from ${registryUrl}…`);
   let payload: CheckoutPayload;
   try {
     payload = await client.checkout(kind, id);
   } catch (error) {
     if (error instanceof RegistryClientError) {
-      throw new CheckoutError(describeFetchFailure(error, kind, id, connection.url));
+      throw new CheckoutError(describeFetchFailure(error, kind, id, registryUrl));
     }
     throw error;
   }
@@ -594,3 +599,60 @@ export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind,
       `(${payload.files.length} source file(s) + ${declarationFileName}).`
   );
 };
+
+/**
+ * Checkout a single component, pattern, or page from the connected registry into this workspace.
+ * Overwriting existing local files requires `--force` or an interactive confirmation.
+ */
+export const checkoutEntity = async (handoff: Handoff, kind: TransferEntityKind, id: string): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  await checkoutSingle(handoff, kind, id, client, connection.url);
+};
+
+/**
+ * Checkout every published component, pattern, or page of the kind into this workspace. Enumerates
+ * the registry's published ids, then checks each out through the shared client. A per-entity failure
+ * is collected and never aborts the rest; the run throws at the end if any entity failed. Overwrite
+ * prompting is per entity (skipped under `--force`).
+ */
+export const checkoutEntities = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+
+  let summaries;
+  try {
+    summaries = await client.listEntities(kind);
+  } catch (error) {
+    if (error instanceof RegistryClientError) {
+      throw new CheckoutError(`Could not list ${kind}s from the registry at ${connection.url}: ${error.message}`);
+    }
+    throw error;
+  }
+
+  if (summaries.length === 0) {
+    Logger.success(`No ${kind}s are published in the registry; nothing to checkout.`);
+    return;
+  }
+
+  let checkedOut = 0;
+  const failed: { id: string; message: string }[] = [];
+  for (const { id } of summaries) {
+    try {
+      await checkoutSingle(handoff, kind, id, client, connection.url);
+      checkedOut += 1;
+    } catch (error) {
+      failed.push({ id, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  Logger.success(
+    `${kind[0].toUpperCase()}${kind.slice(1)}s checkout complete — ${checkedOut} checked out${failed.length ? `, ${failed.length} failed` : ''}.`
+  );
+  if (failed.length > 0) {
+    for (const failure of failed) {
+      Logger.error(`  - ${failure.id}: ${failure.message}`);
+    }
+    throw new CheckoutError(`${failed.length} ${kind}(s) failed to checkout.`);
+  }
+};

package/src/registry/client.ts

@@ -8,7 +8,7 @@
  * and the browser both provide it), so this module stays runtime-agnostic.
  */
 
-import type { CheckoutPayload, TransferEntityKind, TransferPackage } from './transfer';
+import type { CheckoutPayload, EntitySummary, TransferEntityKind, TransferPackage } from './transfer';
 import type { TokenSetCheckoutPayload, TokenSetSummary, TokenSetTransferPackage } from './tokens/transfer';
 import type { AssetCollectionCheckoutPayload, AssetCollectionSummary, AssetCollectionTransferPackage } from './assets/transfer';
 
@@ -55,6 +55,7 @@ export interface RegistryClientOptions {
 export interface RegistryClient {
   publish(kind: TransferEntityKind, id: string, pkg: TransferPackage): Promise<RegistryEnvelope>;
   checkout(kind: TransferEntityKind, id: string): Promise<CheckoutPayload>;
+  listEntities(kind: TransferEntityKind): Promise<EntitySummary[]>;
   listTokenSets(): Promise<TokenSetSummary[]>;
   publishTokens(pkg: TokenSetTransferPackage): Promise<RegistryEnvelope>;
   checkoutTokens(id: string): Promise<TokenSetCheckoutPayload>;
@@ -154,6 +155,11 @@ export const createRegistryClient = ({ baseUrl, accessToken }: RegistryClientOpt
       }
       return envelope.data;
     },
+    /** List the registry's entities of one kind (id + build hashes) for skip-unchanged / bulk checkout. */
+    async listEntities(kind: TransferEntityKind): Promise<EntitySummary[]> {
+      const envelope = await request<{ entities: EntitySummary[] }>('GET', `/api/registry/transfer/${kind}`);
+      return envelope.data?.entities ?? [];
+    },
     /** List the registry's token sets (id + kind + source hash) for skip-unchanged / bulk checkout. */
     async listTokenSets(): Promise<TokenSetSummary[]> {
       const envelope = await request<{ sets: TokenSetSummary[] }>('GET', '/api/registry/transfer/tokens');

package/src/registry/db/client.ts

@@ -1,24 +1,24 @@
 /**
  * Bundled Drizzle client + migrator for the registry database.
  *
- * The package ships both built-in adapters (`pg` and `neon`) and the Drizzle client/migrator, so a
+ * The package ships both built-in drivers (`pg` and `neon`) and the Drizzle client/migrator, so a
  * consuming project needs no global Drizzle install or separate CLI. Driver modules are loaded
- * lazily (dynamic import) for the selected adapter only, so workspace dev/build never pulls the
+ * lazily (dynamic import) for the selected driver only, so workspace dev/build never pulls the
  * Postgres/Neon drivers into memory when the registry is not in use.
  */
 
 import type { NeonDatabase } from 'drizzle-orm/neon-serverless';
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
-import type { RegistryDatabaseAdapter } from './adapter';
+import type { RegistryDatabaseDriver } from './driver';
 import * as schema from './schema';
 
-/** Typed Drizzle database over the registry schema, regardless of which adapter backs it. */
+/** Typed Drizzle database over the registry schema, regardless of which driver backs it. */
 export type RegistryDatabase = NodePgDatabase<typeof schema> | NeonDatabase<typeof schema>;
 
 /** A live registry database connection plus its lifecycle operations. */
 export interface RegistryDbConnection {
-  /** Selected adapter that produced this connection. */
-  adapter: RegistryDatabaseAdapter;
+  /** Selected driver that produced this connection. */
+  driver: RegistryDatabaseDriver;
   /** Typed Drizzle database. */
   db: RegistryDatabase;
   /** Apply the package-owned migrations found in `migrationsFolder`. */
@@ -28,20 +28,20 @@ export interface RegistryDbConnection {
 }
 
 export interface CreateRegistryDbConnectionParams {
-  adapter: RegistryDatabaseAdapter;
+  driver: RegistryDatabaseDriver;
   connectionString: string;
 }
 
 /**
- * Create a registry database connection for the resolved adapter. Both adapters target the
+ * Create a registry database connection for the resolved driver. Both drivers target the
  * Postgres dialect and share the same schema, so the returned connection is interchangeable for
  * migration and (later) the registry store.
  */
 export const createRegistryDbConnection = async ({
-  adapter,
+  driver,
   connectionString,
 }: CreateRegistryDbConnectionParams): Promise<RegistryDbConnection> => {
-  if (adapter === 'neon') {
+  if (driver === 'neon') {
     const { Pool, neonConfig } = await import('@neondatabase/serverless');
     // Neon's serverless driver needs a WebSocket constructor in Node; reuse the bundled `ws`.
     const ws = await import('ws');
@@ -59,7 +59,7 @@ export const createRegistryDbConnection = async ({
     const db = drizzle(pool, { schema });
 
     return {
-      adapter,
+      driver,
       db,
       migrate: (migrationsFolder: string) => migrate(db, { migrationsFolder }),
       close: () => pool.end(),
@@ -80,7 +80,7 @@ export const createRegistryDbConnection = async ({
   const db = drizzle(pool, { schema });
 
   return {
-    adapter,
+    driver,
     db,
     migrate: (migrationsFolder: string) => migrate(db, { migrationsFolder }),
     close: () => pool.end(),

package/src/registry/db/{adapter.ts → driver.ts}

@@ -1,17 +1,19 @@
 /**
- * Registry database adapter resolution.
+ * Registry database driver resolution.
  *
- * `runtime.registry.database.adapter` selects one of two built-in adapters shipped with the
- * `handoff-app` package — `pg` (default) and `neon` — both targeting the Postgres dialect.
- * `build --target registry` and `db:migrate` resolve the **same** adapter so build and migration
- * never diverge. Connection credentials are referenced by environment-variable name only and
- * resolved to a value at runtime; the value is never stored in config.
+ * PostgreSQL is the supported database. `runtime.registry.database.driver` selects one of two
+ * built-in connection drivers shipped with the `handoff-app` package — `pg` (default) and `neon` —
+ * both targeting the same Postgres dialect over one package-owned schema and migration set. The
+ * driver picks *how* to connect, not *which* database engine to use. `build --target registry` and
+ * `db:migrate` resolve the **same** driver so build and migration never diverge. Connection
+ * credentials are referenced by environment-variable name only and resolved to a value at runtime;
+ * the value is never stored in config.
  */
 
 import type { Config } from '../../types/config';
 
-/** Built-in registry database adapter. Both ship with the package and target Postgres. */
-export type RegistryDatabaseAdapter = 'pg' | 'neon';
+/** Built-in registry database connection driver. Both ship with the package and target Postgres. */
+export type RegistryDatabaseDriver = 'pg' | 'neon';
 
 /** Default env-var name holding the database connection string. */
 export const DEFAULT_DATABASE_URL_ENV = 'DATABASE_URL';
@@ -19,13 +21,13 @@ export const DEFAULT_DATABASE_URL_ENV = 'DATABASE_URL';
 /** Default env-var name holding the registry management API bearer token. */
 export const DEFAULT_REGISTRY_API_TOKEN_ENV = 'HANDOFF_REGISTRY_API_TOKEN';
 
-/** Default registry database adapter when none is configured. */
-export const DEFAULT_REGISTRY_ADAPTER: RegistryDatabaseAdapter = 'pg';
+/** Default registry database driver when none is configured. */
+export const DEFAULT_REGISTRY_DRIVER: RegistryDatabaseDriver = 'pg';
 
 /** Fully resolved registry database connection inputs. */
 export interface ResolvedRegistryDatabase {
-  /** Selected built-in adapter. */
-  adapter: RegistryDatabaseAdapter;
+  /** Selected built-in driver. */
+  driver: RegistryDatabaseDriver;
   /** Name of the env var the connection string was read from. */
   databaseUrlEnv: string;
   /** Resolved connection string (never persisted in config). */
@@ -48,9 +50,9 @@ export const resolveApiTokenEnv = (config: Config | null | undefined): string =>
   return configured || DEFAULT_REGISTRY_API_TOKEN_ENV;
 };
 
-/** Resolve the configured registry adapter (defaults to `pg`). */
-export const resolveRegistryAdapter = (config: Config | null | undefined): RegistryDatabaseAdapter => {
-  return config?.runtime?.registry?.database?.adapter ?? DEFAULT_REGISTRY_ADAPTER;
+/** Resolve the configured registry database driver (defaults to `pg`). */
+export const resolveRegistryDriver = (config: Config | null | undefined): RegistryDatabaseDriver => {
+  return config?.runtime?.registry?.database?.driver ?? DEFAULT_REGISTRY_DRIVER;
 };
 
 /**
@@ -59,7 +61,7 @@ export const resolveRegistryAdapter = (config: Config | null | undefined): Regis
  * message instead of failing deep inside the driver.
  */
 export const resolveRegistryDatabase = (config: Config | null | undefined): ResolvedRegistryDatabase => {
-  const adapter = resolveRegistryAdapter(config);
+  const driver = resolveRegistryDriver(config);
   const databaseUrlEnv = resolveDatabaseUrlEnv(config);
   const connectionString = process.env[databaseUrlEnv]?.trim();
 
@@ -70,5 +72,5 @@ export const resolveRegistryDatabase = (config: Config | null | undefined): Reso
     );
   }
 
-  return { adapter, databaseUrlEnv, connectionString };
+  return { driver, databaseUrlEnv, connectionString };
 };

package/src/registry/db/index.ts

@@ -15,15 +15,15 @@ export type { ArtifactBuildStatus as RegistryBuildStatus } from '../../artifacts
 
 export {
   DEFAULT_DATABASE_URL_ENV,
-  DEFAULT_REGISTRY_ADAPTER,
+  DEFAULT_REGISTRY_DRIVER,
   DEFAULT_REGISTRY_API_TOKEN_ENV,
   resolveApiTokenEnv,
   resolveDatabaseUrlEnv,
-  resolveRegistryAdapter,
+  resolveRegistryDriver,
   resolveRegistryDatabase,
-  type RegistryDatabaseAdapter,
+  type RegistryDatabaseDriver,
   type ResolvedRegistryDatabase,
-} from './adapter';
+} from './driver';
 
 export {
   createRegistryDbConnection,

package/src/registry/db/migrate.ts

@@ -2,7 +2,7 @@
  * Registry migration runner.
  *
  * `handoff-app db:migrate` reads the consuming project's config + DB env vars, resolves the same
- * `runtime.registry.database.adapter` used at runtime/build, and applies the package-owned
+ * `runtime.registry.database.driver` used at runtime/build, and applies the package-owned
  * migration set with the bundled Drizzle migrator. Migrations are resolved relative to the
  * installed package (not the consuming project), so the schema is versioned with the tool. This
  * runs independently of `build`.
@@ -12,7 +12,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import type Handoff from '../../';
 import { Logger } from '../../utils/logger';
-import { resolveRegistryDatabase } from './adapter';
+import { resolveRegistryDatabase } from './driver';
 import { createRegistryDbConnection } from './client';
 
 /**
@@ -33,7 +33,7 @@ export const runRegistryMigrations = async (handoff: Handoff): Promise<void> =>
     throw new Error('Handoff is not initialized; cannot resolve registry database configuration.');
   }
 
-  const { adapter, databaseUrlEnv, connectionString } = resolveRegistryDatabase(handoff.config);
+  const { driver, databaseUrlEnv, connectionString } = resolveRegistryDatabase(handoff.config);
 
   const migrationsFolder = getMigrationsFolder(handoff);
   const journalPath = path.join(migrationsFolder, 'meta', '_journal.json');
@@ -44,9 +44,9 @@ export const runRegistryMigrations = async (handoff: Handoff): Promise<void> =>
     );
   }
 
-  Logger.info(`Running registry migrations (adapter: "${adapter}", database url from "${databaseUrlEnv}").`);
+  Logger.info(`Running registry migrations (driver: "${driver}", database url from "${databaseUrlEnv}").`);
 
-  const connection = await createRegistryDbConnection({ adapter, connectionString });
+  const connection = await createRegistryDbConnection({ driver, connectionString });
   try {
     await connection.migrate(migrationsFolder);
     Logger.success('Registry migrations applied successfully.');

package/src/registry/publish/index.ts

@@ -1,7 +1,7 @@
 /**
  * Connected-workspace publish orchestration.
  *
- * `publish <component|pattern|page> <id>` prepares one entity and uploads its record, source files,
+ * `publish <components|patterns|pages> <id>` prepares one entity and uploads its record, source files,
  * applicable rendered artifacts, and build metadata through the shared registry client.
  *
  * The build is targeted: a component builds the global artifacts + that component; a pattern builds
@@ -17,7 +17,7 @@ import { processPatterns } from '../../transformers/preview/pattern/builder';
 import { Logger } from '../../utils/logger';
 import { createRegistryClient, RegistryClientError } from '../client';
 import { resolveRegistryConnection } from '../connection';
-import type { TransferEntityKind } from '../transfer';
+import type { EntitySummary, TransferEntityKind } from '../transfer';
 import { describeUploadFailure } from './errors';
 import { assertRequiredArtifactsPresent, buildPublishPackage, PublishPackageError } from './package';
 
@@ -126,3 +126,101 @@ export const publishEntity = async (handoff: Handoff, kind: TransferEntityKind,
 
   Logger.success(`Published ${kind} "${id}" to the registry.`);
 };
+
+/** The published-content hash a bulk publish compares for skip-unchanged (artifact for rendered kinds, source for pages). */
+const entityHash = (value: { artifactHash?: string; sourceHash?: string }): string | undefined => value.artifactHash ?? value.sourceHash;
+
+/**
+ * Run one build covering every entity of the kind, so a bulk publish builds once instead of per id.
+ * Pages carry no rendered artifacts. Components need the global artifacts + all components; patterns
+ * additionally need all patterns composed (each references pre-built component HTML).
+ */
+const runBulkBuild = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
+  if (kind === 'page') {
+    return;
+  }
+  await buildMainJS(handoff);
+  await buildMainCss(handoff);
+  await processComponents(handoff);
+  if (kind === 'pattern') {
+    await processPatterns(handoff);
+  }
+};
+
+/** List every declared entity id of the kind from the workspace store. */
+const listWorkspaceEntityIds = async (handoff: Handoff, kind: TransferEntityKind): Promise<string[]> => {
+  const store = kind === 'component' ? handoff.store.components : kind === 'pattern' ? handoff.store.patterns : handoff.store.pages;
+  return (await store.list()).map((entity) => entity.id);
+};
+
+/**
+ * Publish every component, pattern, or page declared in this connected workspace. Builds the kind
+ * once, assembles each entity's package, skips entities whose content hash already matches the
+ * registry (unless `--force`), and reports published/unchanged/failed counts. A per-entity failure is
+ * collected and never aborts the rest; the run throws at the end if any entity failed.
+ */
+export const publishEntities = async (handoff: Handoff, kind: TransferEntityKind): Promise<void> => {
+  const connection = resolveConnectionOrThrow(handoff);
+
+  Logger.info(`Building ${kind}s for publish…`);
+  await runBulkBuild(handoff, kind);
+
+  const ids = await listWorkspaceEntityIds(handoff, kind);
+  if (ids.length === 0) {
+    Logger.success(`No ${kind}s are declared in this workspace; nothing to publish.`);
+    return;
+  }
+
+  const client = createRegistryClient({ baseUrl: connection.url, accessToken: connection.accessToken });
+  let remote: EntitySummary[] = [];
+  if (!handoff.force) {
+    try {
+      remote = await client.listEntities(kind);
+    } catch {
+      // If the summary listing fails we simply publish everything (the server still overwrites in place).
+      Logger.info(`Could not read current registry ${kind}s; publishing all.`);
+    }
+  }
+  const remoteHashById = new Map(remote.map((entry) => [entry.id, entityHash(entry)]));
+
+  let published = 0;
+  let unchanged = 0;
+  const failed: { id: string; message: string }[] = [];
+
+  for (const id of ids) {
+    try {
+      const pkg = await buildPublishPackage(handoff, kind, id);
+      assertRequiredArtifactsPresent(pkg);
+
+      const remoteHash = remoteHashById.get(id);
+      const localHash = entityHash(pkg.build);
+      if (!handoff.force && remoteHash && localHash && remoteHash === localHash) {
+        unchanged += 1;
+        Logger.info(`Unchanged: ${id}`);
+        continue;
+      }
+
+      await client.publish(kind, id, pkg);
+      published += 1;
+      Logger.info(`Published: ${id} (${pkg.artifacts.length} artifact(s), ${pkg.files.length} source file(s))`);
+    } catch (error) {
+      const message =
+        error instanceof RegistryClientError
+          ? describeUploadFailure(error, connection.url, 'package')
+          : error instanceof Error
+            ? error.message
+            : String(error);
+      failed.push({ id, message });
+    }
+  }
+
+  Logger.success(
+    `${kind[0].toUpperCase()}${kind.slice(1)}s publish complete — ${published} published, ${unchanged} unchanged${failed.length ? `, ${failed.length} failed` : ''}.`
+  );
+  if (failed.length > 0) {
+    for (const failure of failed) {
+      Logger.error(`  - ${failure.id}: ${failure.message}`);
+    }
+    throw new PublishError(`${failed.length} ${kind}(s) failed to publish.`);
+  }
+};

package/src/registry/transfer.ts

@@ -80,3 +80,17 @@ export interface CheckoutPayload {
   item: Record<string, unknown>;
   files: TransferFile[];
 }
+
+/**
+ * A published entity's summary from `GET /api/registry/transfer/{component|pattern|page}`. Carries
+ * the build hashes so a connected workspace can skip unchanged entities on a bulk publish and
+ * enumerate published ids for a bulk checkout. Components/patterns key on `artifactHash`; pages key
+ * on `sourceHash`.
+ */
+export interface EntitySummary {
+  id: string;
+  kind: TransferEntityKind;
+  status?: string;
+  artifactHash?: string;
+  sourceHash?: string;
+}

package/src/types/config.ts

@@ -138,8 +138,12 @@ export interface HandoffRuntimeConfig {
     /** Name of the env var holding the registry API token. @default "HANDOFF_REGISTRY_API_TOKEN" */
     apiTokenEnv?: string;
     database?: {
-      /** @default "pg" */
-      adapter?: 'pg' | 'neon';
+      /**
+       * PostgreSQL is the supported database. `driver` selects the built-in connection driver — how
+       * to connect, not which engine — over the same package-owned Postgres schema and migrations.
+       * @default "pg"
+       */
+      driver?: 'pg' | 'neon';
     };
     /**
      * Where published asset blobs (icons/logos/fonts/sprites/archives) are stored. Defaults to the
@@ -214,7 +218,7 @@ export interface Config {
    */
   entries?: ConfigEntries;
   /**
-   * Override URLs for the asset zip download links. When unset, each link defaults to the canonical,
+   * Override URLs for the asset zip download links. When unset, each link defaults to the
    * basePath-aware asset route `{basePath}/api/docs/assets/{collection}/{collection}.zip`, served by
    * the docs read API in every runtime mode (from the DB in registry mode, from statically
    * materialized files in a static export).

package/templates/default/README.md.tpl

@@ -12,4 +12,43 @@ A design system documentation site powered by Handoff App.
 
 - `npm run fetch` - Fetch design data from Figma
 - `npm run start` - Start the documentation server
-- `npm run build` - Build for production
+- `npm run dev` - Start the server in watch mode
+- `npm run build` - Build the documentation site
+- `npm run db:migrate` - Apply registry database migrations
+
+## Deploying
+
+Handoff builds two deployment shapes:
+
+- **Static** — plain files served by any static file server or CDN. Build with
+  `handoff-app build --target static`. The simplest to deploy and run.
+- **Registry** — a live, database-backed Node app that serves a shared catalog.
+  Build with `handoff-app build --target registry`, run it on any Node host, and
+  provide a Postgres `DATABASE_URL`. The more capable, actively evolving option,
+  and the recommended path for a design system you plan to grow.
+
+Add `--package vercel` to either build to produce a `.vercel/output` bundle. If
+you scaffolded a `vercel.json`, it runs the build for the deployment you chose;
+edit its `buildCommand` to switch.
+
+## Registry mode
+
+New projects run in **workspace mode**, which needs no database and is the default
+for building and iterating locally. The database-backed **registry mode** lets you
+publish and share a design system across projects and is where Handoff's
+capabilities are expanding, so it's the recommended path as your design system
+grows. See the Handoff docs for setting up the database and publishing.
+
+### Database migrations
+
+A registry deployment stores its catalog in Postgres, so its schema has to be
+migrated before you deploy new code. Run this against the target database:
+
+```bash
+npm run db:migrate
+```
+
+It reads `DATABASE_URL` from the environment and applies the migrations bundled
+with Handoff. It runs on its own, separate from build and start, so use it as a
+release step (for example in CI/CD). Static deployments don't use a database and
+can skip it.

package/templates/default/gitignore.tpl

@@ -1,7 +1,22 @@
+# Dependencies
 node_modules/
-.env
+
+# Build output
 dist/
-.next/
 out/
-.DS_Store
+.next/
+
+# Generated build artifacts
+public/api
+
+# Environment
+.env
+
+# Deployment
+.vercel
+
+# Logs
 *.log
+
+# OS files
+.DS_Store