@@ -0,0 +1,5 @@
+---
+'zero-swift': patch
+---
+
+`zero-swift --help` prints usage, and a missing schema, samples, or config file or an unknown option gets a one-line message instead of a stack trace.
@@ -8,6 +8,8 @@ name: zbugs screenshots
 # UI tests run the ZeroVirtual test app (swift/TestHost), which needs no
 # backend.
 # Path-filtered to the app and the UI layer: macOS runners are slow to start.
+# Within that, the changes job picks the jobs a change needs: the screenshots
+# for zbugs, the virtual list suites for the test app (swift/TestHost).
 
 on:
   push:
@@ -38,8 +40,49 @@ permissions:
   contents: read
 
 jobs:
+  changes:
+    name: Changed paths
+    runs-on: ubuntu-latest
+    outputs:
+      zbugs: ${{ steps.paths.outputs.zbugs }}
+      testhost: ${{ steps.paths.outputs.testhost }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - id: paths
+        env:
+          EVENT: ${{ github.event_name }}
+          PR_BASE: ${{ github.event.pull_request.base.sha }}
+          BEFORE: ${{ github.event.before }}
+        run: |
+          case "$EVENT" in
+            pull_request) base="$(git merge-base "$PR_BASE" HEAD || true)" ;;
+            push) base="$BEFORE" ;;
+            *) base='' ;;
+          esac
+          # A manual run, a new branch, or a force push runs everything.
+          if [ -n "$base" ] && git cat-file -e "$base^{commit}" 2>/dev/null; then
+            files="$(git diff --name-only "$base" HEAD)"
+          else
+            files=all
+          fi
+          shared='^(swift/Sources/(ZeroUI|ZeroVirtual|ZeroTesting)/|\.github/workflows/zbugs-screenshots\.yml$)'
+          needs() {
+            if [ "$files" = all ] || grep -qE "$1|$shared" <<<"$files"; then
+              echo true
+            else
+              echo false
+            fi
+          }
+          echo "zbugs=$(needs '^apps/zbugs-swift/')" >> "$GITHUB_OUTPUT"
+          echo "testhost=$(needs '^swift/TestHost/')" >> "$GITHUB_OUTPUT"
+
   screenshots:
     name: zbugs screenshots (iPhone, iPad, and macOS)
+    needs: changes
+    if: needs.changes.outputs.zbugs == 'true'
     runs-on: macos-26
     timeout-minutes: 60
     steps:
@@ -153,6 +196,8 @@ jobs:
     # Each platform and suite in its own job: together they outrun a job's
     # timeout (the frame probe's scripts drive minutes of scrolling).
     name: Virtual list UI tests (${{ matrix.platform }}, ${{ matrix.suite }})
+    needs: changes
+    if: needs.changes.outputs.testhost == 'true'
     runs-on: macos-26
     timeout-minutes: 45
     strategy:
 
@@ -37,9 +37,15 @@ final class ScreenshotTests: XCTestCase {
     settle()
     snapshot(app, "1 Issues")
 
-    // An issue with its comments.
+    // An issue with its comments. A tap while the list is still taking in
+    // the sync can land on a row as it's replaced, so tap again if the issue
+    // hasn't opened.
     press(firstIssue)
-    if expect(app, app.buttons["Comment"], "the issue's comment button") {
+    let comment = app.buttons["Comment"]
+    if !comment.waitForExistence(timeout: 10), firstIssue.isHittable {
+      press(firstIssue)
+    }
+    if expect(app, comment, "the issue's comment button") {
       settle()
       snapshot(app, "2 Issue")
     }
 
@@ -6,6 +6,7 @@ truth, and this tool generates what the Swift client needs from them.
 
 ```sh
 npm install --save-dev zero-swift
+npx zero-swift --help
 ```
 
 It needs Node 22.18 or later, which loads TypeScript files directly. It also
 
@@ -1,4 +1,12 @@
 #!/usr/bin/env node
-import {main} from './cli.ts';
+import {main, UsageError} from './cli.ts';
 
-process.exitCode = await main(process.argv.slice(2));
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (e) {
+  if (!(e instanceof UsageError)) {
+    throw e;
+  }
+  process.stderr.write(`zero-swift: ${e.message}\n`);
+  process.exitCode = 1;
+}
@@ -26,16 +26,44 @@ import type {Schema} from '../../zero-types/src/schema.ts';
 import {generate, type Config} from './generate.ts';
 import {readCustomTypes} from './types.ts';
 
+const usage = `Usage:
+  zero-swift codegen [--schema schema.ts] [--out Schema.swift]
+                     [--config zero-swift.json] [--check]
+  zero-swift drift record [--samples drift-samples.ts]
+                          [--out drift-vectors.json] [--check]
+
+codegen generates Swift from the app's TypeScript schema. Options override
+zero-swift.json, which is read when present.
+drift record runs the app's TS queries and mutators on samples and records
+what they did, for the Swift drift test.
+--check fails when the output is out of date instead of writing it.
+
+Docs: https://github.com/wevm/zero/tree/main/packages/zero-swift-cli
+`;
+
+/** A mistake in how the CLI was run: printed without a stack. */
+export class UsageError extends Error {}
+
+function mustExist(path: string, message: string) {
+  if (!existsSync(path)) {
+    throw new UsageError(message);
+  }
+}
+
 export async function codegenFile(config: Config, cwd: string) {
   const schemaPath = resolve(cwd, config.schema ?? 'schema.ts');
+  mustExist(
+    schemaPath,
+    `Schema ${relative(cwd, schemaPath)} doesn't exist. Pass --schema, or set "schema" in zero-swift.json.`,
+  );
   const exportName = config.export ?? 'schema';
   const module = (await import(pathToFileURL(schemaPath).href)) as Record<
     string,
     unknown
   >;
   const schema = module[exportName] as Schema | undefined;
   if (!schema || typeof schema !== 'object' || !('tables' in schema)) {
-    throw new Error(
+    throw new UsageError(
       `${schemaPath} does not export a schema as "${exportName}"`,
     );
   }
@@ -49,26 +77,41 @@ export async function codegenFile(config: Config, cwd: string) {
 }
 
 export async function main(argv: string[]): Promise<number> {
-  const {values, positionals} = parseArgs({
-    args: argv,
-    allowPositionals: true,
-    options: {
-      schema: {type: 'string'},
-      out: {type: 'string'},
-      config: {type: 'string'},
-      samples: {type: 'string'},
-      check: {type: 'boolean'},
-    },
-  });
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        schema: {type: 'string'},
+        out: {type: 'string'},
+        config: {type: 'string'},
+        samples: {type: 'string'},
+        check: {type: 'boolean'},
+        help: {type: 'boolean', short: 'h'},
+      },
+    });
+  } catch (e) {
+    process.stderr.write(`${(e as Error).message}\n\n${usage}`);
+    return 2;
+  }
+  const {values, positionals} = parsed;
   const [command = 'codegen', subcommand] = positionals;
+  if (values.help || command === 'help') {
+    process.stdout.write(usage);
+    return 0;
+  }
   const cwd = process.cwd();
   if (command === 'drift' && subcommand === 'record') {
+    const samples = resolve(cwd, values.samples ?? 'drift-samples.ts');
+    mustExist(
+      samples,
+      `Samples file ${relative(cwd, samples)} doesn't exist. Pass --samples.`,
+    );
     // Loaded here: the recorder runs the app's `@rocicorp/zero`, which
     // codegen does not need.
     const {recordDriftFile} = await import('./drift.ts');
-    const vectors = await recordDriftFile(
-      resolve(cwd, values.samples ?? 'drift-samples.ts'),
-    );
+    const vectors = await recordDriftFile(samples);
     return writeOutput(
       resolve(cwd, values.out ?? 'drift-vectors.json'),
       vectors,
@@ -77,14 +120,19 @@ export async function main(argv: string[]): Promise<number> {
     );
   }
   if (command !== 'codegen') {
-    process.stderr.write(`Unknown command "${positionals.join(' ')}"\n`);
+    process.stderr.write(
+      `Unknown command "${positionals.join(' ')}"\n\n${usage}`,
+    );
     return 2;
   }
   const configPath =
     values.config ??
     (existsSync(resolve(cwd, 'zero-swift.json'))
       ? 'zero-swift.json'
       : undefined);
+  if (configPath) {
+    mustExist(resolve(cwd, configPath), `Config ${configPath} doesn't exist.`);
+  }
   const fileConfig = configPath
     ? (JSON.parse(readFileSync(resolve(cwd, configPath), 'utf8')) as Config)
     : {};
 
@@ -1,7 +1,7 @@
 import {readFileSync, writeFileSync} from 'node:fs';
 import {fileURLToPath} from 'node:url';
 import {expect, test} from 'vitest';
-import {codegenFile} from './cli.ts';
+import {codegenFile, main, UsageError} from './cli.ts';
 import type {Config} from './generate.ts';
 
 const repo = fileURLToPath(new URL('../../../', import.meta.url));
@@ -94,3 +94,11 @@ for (const {name, dir = '', config} of fixtures) {
     expect(swift).toBe(readFileSync(path, 'utf8'));
   });
 }
+
+test('a missing schema is a usage error, not a crash', async () => {
+  await expect(main(['--schema', 'no-such-schema.ts'])).rejects.toThrow(
+    new UsageError(
+      `Schema no-such-schema.ts doesn't exist. Pass --schema, or set "schema" in zero-swift.json.`,
+    ),
+  );
+});
@@ -30,6 +30,7 @@ targets: [
   .target(name: "App", dependencies: [
     .product(name: "Zero", package: "zero-swift"),
     .product(name: "ZeroUI", package: "zero-swift"),  // SwiftUI, UIKit, AppKit
+    .product(name: "ZeroVirtual", package: "zero-swift"),  // long lists
   ]),
   .testTarget(name: "AppTests", dependencies: [
     .product(name: "ZeroTesting", package: "zero-swift"),
@@ -68,6 +69,43 @@ struct IssueList: View {
 zero.mutate(IssueMutators.create(.init(id: newID(), title: "Crash on launch", created: now)))
 ```
 
+## Long lists
+
+`ZeroVirtual` is `@rocicorp/zero-virtual` for Swift. A `ZeroVirtualizer`
+pages a list's rows in from your queries as it scrolls, runs at most three
+queries, and drops rows far from the screen. It can open at a row
+(`permalinkID`) or where the list was (`scrollState`). What's on screen stays
+put as pages load, rows go, and rows change height.
+
+```swift
+import ZeroVirtual
+
+let issues = ZeroVirtualizer(
+  zero: zero, listContext: filter, estimatedRowHeight: 56,
+  rowKey: \.id, toStartRow: { IssueStart(id: $0.id, modified: $0.modified) },
+  pageQuery: { page, filter in IssueQueries.page(filter, page) },
+  rowQuery: { row, filter in IssueQueries.byID(filter, row.id) })
+
+// SwiftUI
+VirtualList(issues, selection: $selected) { item, isSelected in
+  IssueRow(issue: item.row, highlighted: isSelected)
+} header: {
+  FilterBar()  // header and footer are optional
+}
+
+// UIKit or AppKit: rows are your own views, reused as they scroll.
+let list = VirtualListView(issues) { item, isSelected, reusing in
+  let row = reusing as? IssueRowView ?? IssueRowView()
+  row.show(item.row, selected: isSelected)
+  return row
+}
+list.onSelect = { id in open(id) }
+```
+
+A tap selects a row, and on macOS so do the arrow keys and j and k. The doc
+comments on `ZeroVirtualizer`, `VirtualList`, and `VirtualListView` cover the
+rest, and `apps/zbugs-swift` uses all three.
+
 ## Documentation
 
 The DocC catalogs in `Sources/*/*.docc` cover the following. Open them in
 
@@ -17,7 +17,7 @@ import Zero
 ///   rowQuery: { row, filter in Queries.issueByID(filter, row.id) })
 /// ```
 ///
-/// A scroll view adapter (`VirtualList`, `VirtualTableAdapter`) attaches
+/// A scroll view adapter (`VirtualList`, `VirtualListView`) attaches
 /// itself and renders `snapshot`.
 @Observable
 @MainActor
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'zero-swift': patch
 +---
++
 +`zero-swift --help` prints usage, and a missing schema, samples, or config file or an unknown option gets a one-line message instead of a stack trace.