diff --git a/.changeset/quiet-roads-return.md b/.changeset/quiet-roads-return.md
new file mode 100644
index 0000000..fb212b1
--- /dev/null
+++ b/.changeset/quiet-roads-return.md
@@ -0,0 +1,11 @@
+---
+"@savvy-web/github-action-builder": minor
+---
+
+## Bug Fixes
+
+Fixed user-configured `build.externals` entries not being honored after the v0.6.4 `node:` interop fix. A change to the rspack externals config structure had caused the trailing string entries to be silently ignored, so configured package names were bundled and hard-failed to resolve instead of being externalized.
+
+## Features
+
+Added `build.ignore` — a `string[]` option listing modules to exclude from the bundle and replace with a throwing stub. Use it for optional transitive dependencies the action never exercises (for example, native modules pulled in as optional plugins by a dependency). Unlike `build.externals` (packages excluded because they are available at runtime), `build.ignore` packages are absent at runtime; code that wraps their `require()` calls in `try/catch` correctly detects them as unavailable.
diff --git a/.claude/design/github-action-builder/architecture.md b/.claude/design/github-action-builder/architecture.md
index 598902c..9878961 100644
--- a/.claude/design/github-action-builder/architecture.md
+++ b/.claude/design/github-action-builder/architecture.md
@@ -243,6 +243,7 @@ const BuildOptionsSchema = Schema.Struct({
   minify: Schema.optionalWith(Schema.Boolean, { default: () => true }),
   sourceMap: Schema.optionalWith(Schema.Boolean, { default: () => false }), // Off by default
   externals: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+  ignore: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
   // target hardcoded to ES2024 internally (Node 24 = V8 12.x)
   // quiet removed (was ncc-specific)
 })
@@ -329,7 +330,8 @@ The output structure is **flat** - all files go directly in `dist/`.
 | ------ | ------- | ----------- |
 | `minify` | `true` | Minify output for smaller bundles |
 | `sourceMap` | `false` | Source maps disabled by default |
-| `externals` | `[]` | Additional packages to exclude (node: always external) |
+| `externals` | `[]` | Packages excluded from the bundle, expected to be available at runtime |
+| `ignore` | `[]` | Packages excluded from the bundle and replaced with a stub that throws if loaded at runtime |
 
 ### Persist-Local Defaults
 
@@ -385,7 +387,8 @@ export default defineConfig({
   build: {
     minify: true,             // Default: true
     sourceMap: false,         // Default: false (disabled for smaller bundles)
-    externals: [],            // Additional packages to exclude (node: always external)
+    externals: [],            // Packages excluded from bundle, available at runtime (node: always external)
+    ignore: [],               // Packages replaced with a throwing stub (takes precedence over externals)
   },
 
   // Validation rules
@@ -488,31 +491,44 @@ const BundleStatsSchema = Schema.Struct({
 
 ### Rsbuild Bundler Configuration
 
+When `build.ignore` is non-empty, `IGNORE_STUB_SOURCE` (a single `throw` statement) is written to the OS temp dir as a `.mjs` file before rsbuild runs. Each ignored specifier is mapped to that stub via `resolve.alias` using a `$`-suffixed key for exact-match aliasing, so rspack substitutes the stub in place of the real module.
+
 ```typescript
+// Stub written to tmpdir() when build.ignore is non-empty
+const IGNORE_STUB_SOURCE = `throw new Error("A module excluded via the build 'ignore' option was loaded at runtime.");\n`;
+
+// resolve.alias entries added when build.ignore is non-empty:
+// { "some-module$": "/tmp/github-action-builder-ignore-stub.mjs" }
+
 const rsbuildConfig = {
   source: { entry: { [entry.type]: entry.path } },
+  resolve: { alias: ignoreAlias },  // conditionally populated from build.ignore
   output: {
     target: "node",
-    module: true,                          // ESM output (experimental)
+    module: true,                   // ESM output (experimental)
     distPath: { root: outputDir },
     filename: { js: "[name].js" },
-    externals: [
-      // Force node: builtins to resolve as CJS so bundled CJS deps that call
-      // __importDefault(require("node:stream")) get real module exports, not
-      // an ESM namespace. Without this, instanceof checks on e.g. Stream throw
-      // "Right-hand side of 'instanceof' is not callable".
-      (data) =>
-        data.request?.startsWith("node:")
-          ? `node-commonjs ${data.request}`
-          : false,
-      ...config.build.externals,
-    ],
-    minify: config.build.minify,           // Default: true
-    sourceMap: config.build.sourceMap       // Default: false
-      ? { js: "source-map" } : false,
+    // A single function makes the whole externalization decision so it never
+    // depends on rspack's array fall-through. Previously, leading the array
+    // with a function caused rspack to stop consulting trailing string entries,
+    // so user-configured externals were bundled and hard-failed to resolve (#81).
+    externals: (data) => {
+      const request = data.request;
+      if (!request) return false;
+      // node: builtins: force CommonJS require() semantics so bundled CJS deps
+      // that call __importDefault(require("node:stream")) get real exports, not
+      // an ESM namespace. Prevents "instanceof is not callable" (#79).
+      if (request.startsWith("node:")) return `node-commonjs ${request}`;
+      // User externals: left as runtime imports. ignore takes precedence —
+      // a module in both lists is handled by resolve.alias, not externalized.
+      if (config.build.externals.includes(request) && !config.build.ignore.includes(request)) return request;
+      return false;
+    },
+    minify: config.build.minify,    // Default: true
+    sourceMap: config.build.sourceMap ? { js: "source-map" } : false,
   },
   performance: {
-    chunkSplit: { strategy: "all-in-one" }, // Single-file output
+    chunkSplit: { strategy: "all-in-one" },  // Single-file output
   },
 };
 ```
@@ -1059,6 +1075,8 @@ Resolved questions from initial design:
 | Output format | ESM (`output.module: true`) | Node 24 actions use `"type": "module"` |
 | Chunk strategy | `all-in-one` | GitHub Actions need single-file per entry |
 | `node:` external type | `node-commonjs` via function external | RegExp external with ESM output resolves builtins as ESM namespace; CJS deps doing `__importDefault(require("node:stream"))` then get a non-callable `.default`, breaking `instanceof`. Function external forces `createRequire(import.meta.url)("node:stream")` which returns real CJS exports. |
+| Externals array form (#81 regression) | Single function replaces function + string array | Leading an `externals` array with a function caused rspack to stop consulting trailing string entries; user-configured string externals were bundled instead of externalized. A single function that handles all cases (`node:` → `node-commonjs`, user strings → default, everything else → bundle) eliminates the fall-through dependency. |
+| `build.ignore` stub mechanism | Throwing `.mjs` stub written to `tmpdir()`, aliased via `resolve.alias` with `$` exact-match suffix | Ignored modules must be removed from the bundle without relying on them being available at runtime (unlike `externals`). A stub that throws gives a clear error message if a module is accidentally loaded. The `$` suffix prevents partial matches (e.g., `foo$` matches `foo` but not `foobar`). `ignore` takes precedence over `externals` — a module in both lists is stubbed. |
 
 ---
 
@@ -1097,11 +1115,16 @@ src/
 
 __test__/
 └── integration/
-    ├── cjs-node-interop.int.test.ts  # Regression test: builds fixture, asserts isStream=true
-    └── fixtures/cjs-node-interop/   # Fixture with action.yml, src/main.ts and hand-authored legacy-cjs-dep.cjs
+    ├── cjs-node-interop.int.test.ts   # Regression: builds fixture, asserts isStream=true
+    ├── string-externals.int.test.ts   # Regression: builds fixture with externals[], asserts module is external not bundled
+    ├── ignore-modules.int.test.ts     # E2E: builds fixture with ignore[], asserts stub throws at load time
+    └── fixtures/
+        ├── cjs-node-interop/          # Fixture with action.yml, src/main.ts and hand-authored legacy-cjs-dep.cjs
+        ├── string-externals/          # Fixture that configures externals to verify array fall-through fix (#81)
+        └── ignore-modules/            # Fixture that configures ignore to verify stub aliasing
 ```
 
-Integration tests (`*.int.test.ts`) are auto-discovered by `@savvy-web/vitest` as a `:int` project. The `cjs-node-interop` fixture exercises the `node-commonjs` external fix end-to-end: it builds via `GitHubAction.create()` with `skipValidation: true` and `persistLocal.enabled: false`, runs `dist/main.js` with Node, and asserts `isStream=true`.
+Integration tests (`*.int.test.ts`) are auto-discovered by `@savvy-web/vitest` as a `:int` project. Each builds its fixture via `GitHubAction.create()` with `skipValidation: true` and `persistLocal.enabled: false`, then runs `dist/main.js` with Node to assert runtime behavior. `cjs-node-interop` asserts `isStream=true` (the `node-commonjs` fix); `string-externals` asserts that user-configured externals are not bundled (the #81 regression fix); `ignore-modules` asserts that the stub throws a descriptive error when an ignored module is imported.
 
 ---
 
diff --git a/.gitignore b/.gitignore
index efb9db8..602fb6a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,4 +34,5 @@ pnpm-release.json
 .claude/plans/
 .claude/plugins-debug.log
 .playwright-mcp
-.mcp.json
\ No newline at end of file
+.mcp.json
+docs/superpowers/
\ No newline at end of file
diff --git a/README.md b/README.md
index afbfa30..ccc6b70 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,23 @@
 # @savvy-web/github-action-builder
 
-A zero-config build tool for creating GitHub Actions from TypeScript source
-code. Bundles your action with [@rsbuild/core](https://github.com/web-infra-dev/rsbuild)
-(rspack-based), validates `action.yml` against GitHub's official schema, and
-outputs production-ready Node.js 24 actions.
+[![npm](https://img.shields.io/npm/v/@savvy-web%2Fgithub-action-builder?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/github-action-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js 24](https://img.shields.io/badge/Node.js-24-5fa04e.svg)](https://nodejs.org/)
+
+Build a GitHub Action from TypeScript source without writing build config. The builder bundles your code with [@rsbuild/core](https://github.com/web-infra-dev/rsbuild) (rspack under the hood) and checks `action.yml` against GitHub's published metadata schema. The output is a single Node.js 24 file you commit to your repo.
 
 ## Features
 
-- **Zero-config** - Auto-detects entry points from `src/main.ts`, `src/pre.ts`,
-  `src/post.ts`
-- **Node.js 24** - Builds modern ESM actions for the latest GitHub Actions
-  runtime
-- **Schema validation** - Validates `action.yml` against GitHub's official
-  metadata specification
-- **Single-file bundles** - All npm dependencies inlined via rsbuild, `node:`
-  builtins externalized, with tree-shaking support
-- **Local testing** - Auto-persists build output for testing with
-  [nektos/act](https://github.com/nektos/act)
+- **No build config required** - Picks up entry points from `src/main.ts`, `src/pre.ts`, `src/post.ts` on its own
+- **Node.js 24** - Emits ESM actions that run on the `node24` GitHub Actions runtime
+- **Schema validation** - Validates `action.yml` against GitHub's official metadata specification
+- **Single-file bundles** - All npm dependencies inlined via rsbuild; `node:` builtins externalized; user-configured `externals` and `ignore` options for optional or native modules
+- **Local testing** - Auto-persists build output for testing with [nektos/act](https://github.com/nektos/act)
 - **CI-aware** - Strict validation in CI, warnings-only locally
 
-## Quick Start
+## Quick start
 
-Create a new GitHub Action project with a single command:
+Scaffold a new GitHub Action project, then build it:
 
 ```bash
 npx @savvy-web/github-action-builder init my-action
@@ -30,8 +26,7 @@ npm install
 npm run build
 ```
 
-That's it! Your action is built and ready. The `init` command generates a
-complete project:
+The `init` command lays down the project:
 
 ```text
 my-action/
@@ -45,10 +40,9 @@ my-action/
 └── tsconfig.json    # TypeScript configuration
 ```
 
-Edit `src/main.ts` with your action logic, then rebuild with `npm run build`.
-Your bundled action is in `dist/main.js`, ready to commit and use.
+Put your action logic in `src/main.ts` and run `npm run build` again. The bundled action lands at `dist/main.js` — commit that file to your repo.
 
-## Basic Usage
+## Basic usage
 
 ### Initialize
 
@@ -78,7 +72,7 @@ npm run validate
 npx @savvy-web/github-action-builder validate
 ```
 
-## Project Structure
+## Project structure
 
 The builder expects this structure:
 
@@ -112,7 +106,7 @@ export default GitHubAction.create({
 });
 ```
 
-## action.yml Requirements
+## action.yml requirements
 
 Your `action.yml` must use Node.js 24:
 
@@ -127,12 +121,12 @@ runs:
 
 ## Documentation
 
-- [Getting Started](./docs/getting-started.md) - Installation and first build
-- [Configuration](./docs/configuration.md) - All configuration options
-- [Local Testing](./docs/local-testing.md) - Testing with nektos/act
-- [CLI Reference](./docs/cli-reference.md) - Complete command reference
-- [Architecture](./docs/architecture.md) - How it works internally
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+- [Getting started](./docs/01-getting-started.md) - Installation and first build
+- [Configuration](./docs/02-configuration.md) - All configuration options
+- [Local testing](./docs/03-local-testing.md) - Testing with nektos/act
+- [CLI reference](./docs/04-cli-reference.md) - Complete command reference
+- [Architecture](./docs/05-architecture.md) - How it works internally
+- [Troubleshooting](./docs/06-troubleshooting.md) - Common issues and solutions
 
 ## Programmatic API
 
@@ -146,10 +140,11 @@ const result = await action.build();
 
 if (result.success) {
   console.log(`Built ${result.build?.entries.length} entry points`);
+  // e.g. "Built 3 entry points"
 }
 ```
 
-## Shared TypeScript Configuration
+## Shared TypeScript configuration
 
 The package exports a base `tsconfig.json` for GitHub Action projects:
 
@@ -159,9 +154,7 @@ The package exports a base `tsconfig.json` for GitHub Action projects:
 }
 ```
 
-This provides sensible defaults for Node.js 24 ESM actions including strict
-mode, ES2022 target, and bundler module resolution. Override or extend as
-needed in your project's `tsconfig.json`.
+It sets up Node.js 24 ESM actions with strict mode, an ES2022 target and bundler module resolution. Override any of it in your own `tsconfig.json`.
 
 ## Requirements
 
diff --git a/__test__/integration/fixtures/ignore-modules/action.yml b/__test__/integration/fixtures/ignore-modules/action.yml
new file mode 100644
index 0000000..01bd763
--- /dev/null
+++ b/__test__/integration/fixtures/ignore-modules/action.yml
@@ -0,0 +1,5 @@
+name: ignore-modules
+description: Integration fixture for the build.ignore option (issue #81).
+runs:
+  using: node24
+  main: dist/main.js
diff --git a/__test__/integration/fixtures/ignore-modules/src/main.ts b/__test__/integration/fixtures/ignore-modules/src/main.ts
new file mode 100644
index 0000000..d2ef813
--- /dev/null
+++ b/__test__/integration/fixtures/ignore-modules/src/main.ts
@@ -0,0 +1,3 @@
+import { xmlAvailable } from "../vendor/optional-loader.cjs";
+
+process.stdout.write(`xmlAvailable=${xmlAvailable}\n`);
diff --git a/__test__/integration/fixtures/ignore-modules/vendor/optional-loader.cjs b/__test__/integration/fixtures/ignore-modules/vendor/optional-loader.cjs
new file mode 100644
index 0000000..49ca0a3
--- /dev/null
+++ b/__test__/integration/fixtures/ignore-modules/vendor/optional-loader.cjs
@@ -0,0 +1,14 @@
+"use strict";
+// Mirrors the optional-dependency pattern used by packages such as cyclonedx:
+// an optional native module is required inside a try/catch, so an absent
+// module is treated as "feature unavailable" rather than crashing the action.
+// "excluded-native-dep" is intentionally NOT present in node_modules.
+Object.defineProperty(exports, "__esModule", { value: true });
+let available;
+try {
+	require("excluded-native-dep");
+	available = true;
+} catch {
+	available = false;
+}
+exports.xmlAvailable = available;
diff --git a/__test__/integration/fixtures/ignore-modules/vendor/optional-loader.d.cts b/__test__/integration/fixtures/ignore-modules/vendor/optional-loader.d.cts
new file mode 100644
index 0000000..c7be9ff
--- /dev/null
+++ b/__test__/integration/fixtures/ignore-modules/vendor/optional-loader.d.cts
@@ -0,0 +1 @@
+export declare const xmlAvailable: boolean;
diff --git a/__test__/integration/fixtures/string-externals/action.yml b/__test__/integration/fixtures/string-externals/action.yml
new file mode 100644
index 0000000..42c6f8d
--- /dev/null
+++ b/__test__/integration/fixtures/string-externals/action.yml
@@ -0,0 +1,5 @@
+name: string-externals
+description: Integration fixture for issue #81 — string externals regression.
+runs:
+  using: node24
+  main: dist/main.js
diff --git a/__test__/integration/fixtures/string-externals/src/main.ts b/__test__/integration/fixtures/string-externals/src/main.ts
new file mode 100644
index 0000000..da7bbc6
--- /dev/null
+++ b/__test__/integration/fixtures/string-externals/src/main.ts
@@ -0,0 +1,8 @@
+import { randomUUID } from "node:crypto";
+
+// "uninstalled-peer-dep" is deliberately NOT present in node_modules. The build
+// can only succeed if the configured string external is honored — otherwise
+// rspack hard-fails with "Module not found". See issue #81.
+import "uninstalled-peer-dep";
+
+process.stdout.write(`id=${randomUUID()}\n`);
diff --git a/__test__/integration/fixtures/string-externals/uninstalled-peer-dep.d.ts b/__test__/integration/fixtures/string-externals/uninstalled-peer-dep.d.ts
new file mode 100644
index 0000000..aa19e4c
--- /dev/null
+++ b/__test__/integration/fixtures/string-externals/uninstalled-peer-dep.d.ts
@@ -0,0 +1,4 @@
+// Ambient declaration so the fixture type-checks. The module is intentionally
+// absent from node_modules — only the bundler's externals handling makes the
+// build resolve it. See issue #81.
+declare module "uninstalled-peer-dep";
diff --git a/__test__/integration/ignore-modules.int.test.ts b/__test__/integration/ignore-modules.int.test.ts
new file mode 100644
index 0000000..14a5cdd
--- /dev/null
+++ b/__test__/integration/ignore-modules.int.test.ts
@@ -0,0 +1,50 @@
+/**
+ * Integration test for the build.ignore option (issue #81 design).
+ *
+ * A module listed in build.ignore must be replaced with a throwing stub, so
+ * the build succeeds even when the module is absent from node_modules, the
+ * bundle carries the stub (not rspack's own missing-module shim), and a
+ * try/catch-guarded require treats the module as unavailable.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { GitHubAction } from "../../src/index.js";
+
+const fixtureDir = resolve(dirname(fileURLToPath(import.meta.url)), "fixtures/ignore-modules");
+const mainJs = join(fixtureDir, "dist", "main.js");
+
+describe("issue #81: build.ignore option", () => {
+	it("replaces ignored modules with a throwing stub", async () => {
+		rmSync(join(fixtureDir, "dist"), { recursive: true, force: true });
+		const action = GitHubAction.create({
+			cwd: fixtureDir,
+			skipValidation: true,
+			config: {
+				build: { minify: false, ignore: ["excluded-native-dep"] },
+				persistLocal: { enabled: false },
+			},
+		});
+		const result = await action.build();
+
+		expect(result.success).toBe(true);
+		expect(existsSync(mainJs)).toBe(true);
+
+		// build.ignore replaces the module with the builder's throwing stub.
+		// Without the feature, rspack instead emits its own missing-module
+		// shim — so the stub's message is the discriminating signal.
+		const bundle = readFileSync(mainJs, "utf8");
+		expect(bundle).toContain("excluded via the build 'ignore' option");
+
+		// At runtime the stubbed require throws; the fixture's try/catch
+		// catches it and reports the optional dependency as unavailable.
+		const output = execFileSync("node", [mainJs], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		expect(output.trim()).toBe("xmlAvailable=false");
+	}, 120_000);
+});
diff --git a/__test__/integration/string-externals.int.test.ts b/__test__/integration/string-externals.int.test.ts
new file mode 100644
index 0000000..a9ccf4a
--- /dev/null
+++ b/__test__/integration/string-externals.int.test.ts
@@ -0,0 +1,44 @@
+/**
+ * Integration regression test for issue #81.
+ *
+ * The builder must honor user-configured string `externals` in addition to
+ * externalizing `node:` builtins. 0.6.4 regressed this: leading the externals
+ * array with a function caused rspack to stop consulting the trailing string
+ * entries, so configured externals were bundled (and hard-failed to resolve)
+ * instead of externalized.
+ */
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { GitHubAction } from "../../src/index.js";
+
+const fixtureDir = resolve(dirname(fileURLToPath(import.meta.url)), "fixtures/string-externals");
+const mainJs = join(fixtureDir, "dist", "main.js");
+
+describe("issue #81: string externals regression", () => {
+	it("externalizes node: builtins and configured string externals", async () => {
+		rmSync(join(fixtureDir, "dist"), { recursive: true, force: true });
+		const action = GitHubAction.create({
+			cwd: fixtureDir,
+			skipValidation: true,
+			config: {
+				build: { minify: false, externals: ["uninstalled-peer-dep"] },
+				persistLocal: { enabled: false },
+			},
+		});
+		const result = await action.build();
+
+		// Build must succeed even though "uninstalled-peer-dep" is not installed —
+		// it resolves only if the configured string external is honored.
+		expect(result.success).toBe(true);
+		expect(existsSync(mainJs)).toBe(true);
+
+		const bundle = readFileSync(mainJs, "utf8");
+		// Configured string external is left as a runtime import, not bundled.
+		expect(bundle).toMatch(/uninstalled-peer-dep/);
+		// node: builtins still externalize (guards the issue #79 fix).
+		expect(bundle).toMatch(/node:crypto/);
+	}, 120_000);
+});
diff --git a/docs/getting-started.md b/docs/01-getting-started.md
similarity index 70%
rename from docs/getting-started.md
rename to docs/01-getting-started.md
index 6a3205b..30d3f3c 100644
--- a/docs/getting-started.md
+++ b/docs/01-getting-started.md
@@ -1,7 +1,6 @@
-# Getting Started
+# Getting started
 
-This guide walks you through setting up your first GitHub Action with
-`@savvy-web/github-action-builder`.
+Set up your first GitHub Action with `@savvy-web/github-action-builder`.
 
 ## Prerequisites
 
@@ -9,9 +8,9 @@ This guide walks you through setting up your first GitHub Action with
 - **npm**, **pnpm**, or **yarn**
 - A GitHub repository for your action
 
-## Quick Start
+## Quick start
 
-Create a new GitHub Action project with a single command:
+Scaffold a new GitHub Action project, then build it:
 
 ```bash
 npx @savvy-web/github-action-builder init my-action
@@ -20,10 +19,9 @@ npm install
 npm run build
 ```
 
-This creates a complete, ready-to-build project. Edit `src/main.ts` with your
-action logic and run `npm run build` again.
+The `init` command generates a project that builds without further setup. Put your action logic in `src/main.ts` and run `npm run build` again.
 
-## Generated Project Structure
+## Generated project structure
 
 The `init` command creates this structure:
 
@@ -39,7 +37,7 @@ my-action/
 └── tsconfig.json    # TypeScript configuration
 ```
 
-## Understanding the Generated Files
+## Understanding the generated files
 
 ### action.config.ts
 
@@ -105,10 +103,7 @@ The generated `tsconfig.json` extends the shared base configuration:
 }
 ```
 
-This provides ES2022 target, strict mode, bundler module resolution, and
-includes patterns for `src/`, `lib/`, `__test__/`, and root-level TypeScript
-files like `action.config.ts`. You can override any setting in your project's
-`tsconfig.json`.
+This provides ES2022 target, strict mode, bundler module resolution, and includes patterns for `src/`, `lib/`, `__test__/`, and root-level TypeScript files like `action.config.ts`. You can override any setting in your project's `tsconfig.json`.
 
 ### src/main.ts
 
@@ -137,9 +132,9 @@ async function run(): Promise<void> {
 run();
 ```
 
-## Alternative Installation Methods
+## Alternative installation methods
 
-### Global Installation
+### Global installation
 
 Install globally to use the `github-action-builder` command anywhere:
 
@@ -147,7 +142,7 @@ Install globally to use the `github-action-builder` command anywhere:
 npm install -g @savvy-web/github-action-builder
 ```
 
-### Project Installation
+### Project installation
 
 Install as a dev dependency (already included in generated projects):
 
@@ -164,9 +159,9 @@ npx @savvy-web/github-action-builder build
 npx @savvy-web/github-action-builder validate
 ```
 
-## Building Your Action
+## Building your action
 
-### First Build
+### First build
 
 Run the build command:
 
@@ -186,16 +181,16 @@ Validating...
 Building...
 
 Build Summary:
-  ✓ main: 474.7 KB (909ms) → dist/main.js
-  ✓ pre: 474.6 KB (632ms) → dist/pre.js
-  ✓ post: 474.6 KB (561ms) → dist/post.js
+  ✓ main: <size> (<time>) → dist/main.js
+  ✓ pre:  <size> (<time>) → dist/pre.js
+  ✓ post: <size> (<time>) → dist/post.js
 
-Total time: 2102ms
+Total time: <total>
 
 Build completed successfully!
 ```
 
-### Understanding the Output
+### Understanding the output
 
 After building, your `dist/` directory contains:
 
@@ -207,15 +202,11 @@ dist/
 └── package.json  # ESM module marker { "type": "module" }
 ```
 
-Each bundled file:
+Each bundled file holds your code and its dependencies in one file, minified by default, ready to run on Node.js 24 in GitHub Actions.
 
-- Contains all your code and dependencies in a single file
-- Is minified by default for smaller size
-- Runs on Node.js 24 in GitHub Actions
+## Validation and type checking
 
-## Validation and Type Checking
-
-### Validate Configuration
+### Validate configuration
 
 Check your `action.yml` and configuration without building:
 
@@ -230,7 +221,7 @@ This verifies:
 - `runs.using` is set to `node24`
 - Required entry points exist
 
-### Type Check
+### Type check
 
 Run TypeScript type checking:
 
@@ -238,28 +229,19 @@ Run TypeScript type checking:
 npm run typecheck
 ```
 
-### CI vs Local Behavior
-
-The builder behaves differently based on environment:
-
-**Local development:**
+### CI vs local behavior
 
-- Validation issues show as warnings
-- Build continues even with warnings
-- Faster feedback during development
+The builder treats validation issues differently depending on where it runs.
 
-**CI environment (GitHub Actions):**
+**Local development:** validation issues show as warnings and the build continues, so you keep working while you fix them.
 
-- Validation issues become errors
-- Build fails on any issue
-- Ensures quality gates in CI pipelines
+**CI environment (GitHub Actions):** validation issues become errors and the build fails, so a broken action never gets past the pipeline.
 
-The CI environment is detected via `CI=true` or `GITHUB_ACTIONS=true` environment
-variables.
+The builder treats itself as running in CI when `CI=true` or `GITHUB_ACTIONS=true` is set.
 
-## Using Your Action
+## Using your action
 
-### Commit the dist Directory
+### Commit the dist directory
 
 GitHub Actions runs the bundled code directly, so commit your `dist/` folder:
 
@@ -269,7 +251,7 @@ git commit -m "Build action"
 git push
 ```
 
-### Reference in Workflows
+### Reference in workflows
 
 Use your action in a workflow:
 
@@ -300,8 +282,8 @@ To publish on the GitHub Marketplace:
 3. Follow GitHub's
    [publishing guide](https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace)
 
-## Next Steps
+## Next steps
 
-- [Configuration](./configuration.md) - Customize build options
-- [CLI Reference](./cli-reference.md) - All available commands
-- [Troubleshooting](./troubleshooting.md) - Common issues and solutions
+- [Configuration](./02-configuration.md) - Customize build options
+- [CLI reference](./04-cli-reference.md) - All available commands
+- [Troubleshooting](./06-troubleshooting.md) - Common issues and solutions
diff --git a/docs/configuration.md b/docs/02-configuration.md
similarity index 63%
rename from docs/configuration.md
rename to docs/02-configuration.md
index d568202..b9e39ac 100644
--- a/docs/configuration.md
+++ b/docs/02-configuration.md
@@ -1,11 +1,10 @@
 # Configuration
 
-This guide covers all configuration options for `@savvy-web/github-action-builder`.
+Every configuration option for `@savvy-web/github-action-builder` and what it does.
 
-## Configuration File
+## Configuration file
 
-Create `action.config.ts` in your project root to customize the build process.
-The file is optional - the builder uses sensible defaults without it.
+Create `action.config.ts` in your project root to customize the build. The file is optional — the builder runs with defaults when it is absent.
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -17,10 +16,9 @@ export default GitHubAction.create({
 });
 ```
 
-The `GitHubAction.create()` helper provides TypeScript autocomplete and validates
-your configuration at build time.
+The `GitHubAction.create()` helper gives you TypeScript autocomplete and checks the configuration at build time.
 
-## Configuration Sections
+## Configuration sections
 
 ### entries
 
@@ -32,7 +30,7 @@ Configure entry point paths for your action.
 | `pre` | `string` | `undefined` | Pre-action hook (runs before main) |
 | `post` | `string` | `undefined` | Post-action hook (runs after main) |
 
-#### Custom Entry Points
+#### Custom entry points
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -46,7 +44,7 @@ export default GitHubAction.create({
 });
 ```
 
-#### Main Only (Default Behavior)
+#### Main only (default behavior)
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -59,10 +57,9 @@ export default GitHubAction.create({
 });
 ```
 
-#### Auto-Detection
+#### Auto-detection
 
-If you do not specify `pre` or `post` in your config, the builder automatically
-detects these files:
+If you do not specify `pre` or `post` in your config, the builder automatically detects these files:
 
 * `src/pre.ts` - included if exists
 * `src/post.ts` - included if exists
@@ -78,10 +75,11 @@ Configure how your action is bundled.
 | `minify` | `boolean` | `true` | Minify output for smaller bundles |
 | `target` | `string` | `"es2022"` | ECMAScript target version |
 | `sourceMap` | `boolean` | `false` | Generate source maps |
-| `externals` | `string[]` | `[]` | Packages to exclude from bundle |
+| `externals` | `string[]` | `[]` | Packages to leave out of the bundle; must be available at runtime |
+| `ignore` | `string[]` | `[]` | Packages to leave out of the bundle and replace with a stub that throws if loaded |
 | `quiet` | `boolean` | `false` | Suppress build output |
 
-#### Development Build with Source Maps
+#### Development build with source maps
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -94,7 +92,7 @@ export default GitHubAction.create({
 });
 ```
 
-#### Exclude Packages from Bundle
+#### Exclude packages from bundle (available at runtime)
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -106,12 +104,23 @@ export default GitHubAction.create({
 });
 ```
 
-#### Build Options Details
+#### Exclude packages from bundle (not available at runtime)
+
+```typescript
+import { GitHubAction } from "@savvy-web/github-action-builder";
+
+export default GitHubAction.create({
+  build: {
+    ignore: ["cpu-features", "bufferutil"],
+  },
+});
+```
+
+#### Build options details
 
 ##### minify
 
-When `true` (default), the bundled output is minified to reduce file size. This
-removes whitespace, shortens variable names, and applies other optimizations.
+When `true` (default), the bundled output is minified to reduce file size. Minification strips whitespace and shortens identifiers.
 
 Disable for easier debugging:
 
@@ -131,14 +140,11 @@ The ECMAScript target for the output. Valid values:
 * `"es2023"`
 * `"es2024"`
 
-The target affects which JavaScript features are used in the output. Since
-GitHub Actions runs Node.js 24, `es2022` or later is recommended.
+The target affects which JavaScript features are used in the output. Since GitHub Actions runs Node.js 24, `es2022` or later is recommended.
 
 ##### sourceMap
 
-When `true`, generates source map files alongside the bundled JavaScript. Source
-maps help with debugging by mapping minified code back to your original
-TypeScript source.
+When `true`, generates source map files alongside the bundled JavaScript. A source map maps the minified output back to your original TypeScript, so a stack trace points at the line you wrote.
 
 Source maps are **disabled by default** because:
 
@@ -156,11 +162,7 @@ build: {
 
 ##### externals
 
-An array of package names to exclude from the bundle. Use this when:
-
-* A package cannot be bundled (native modules)
-* You want to reduce bundle size for packages that will be installed separately
-* Testing with mocked dependencies
+An array of package names to leave out of the bundle. These packages stay out of `dist/main.js` and must be available in the action's runtime environment — installed in the action's `node_modules`. Use it for packages that cannot be bundled, or that you install alongside the action.
 
 ```typescript
 build: {
@@ -168,13 +170,32 @@ build: {
 }
 ```
 
-**Note:** External packages must be installed in the action's runtime
-environment, which is not typical for GitHub Actions. Use sparingly.
+**Note:** Relying on runtime-installed packages is unusual for GitHub Actions. Most actions bundle everything. Reach for `externals` only when bundling will not work. For optional transitive dependencies that the action never loads, use [`ignore`](#ignore) instead.
+
+##### ignore
+
+An array of package names to leave out of the bundle and replace with a stub that throws a descriptive error if the module is ever loaded at runtime. Use this for optional transitive dependencies — native modules or optional peer dependencies that the action's code guards with a `try/catch` and never exercises on the GitHub Actions runner.
+
+```typescript
+build: {
+  ignore: ["cpu-features", "bufferutil"],
+}
+```
+
+The difference from `externals`:
+
+| Option | Bundled? | Available at runtime? | What happens if loaded? |
+| --- | --- | --- | --- |
+| `externals` | No | Must be | Resolves normally |
+| `ignore` | No | No | Throws a descriptive error |
+
+If a module appears in both lists, `ignore` takes precedence — the stub is applied and the module is not externalized.
+
+Matching is exact: `ignore: ["cpu-features"]` stubs `cpu-features` but not a subpath import such as `cpu-features/native`. If a dependency reaches an ignored module through a subpath, add that subpath specifier to the list as well.
 
 ##### quiet
 
-When `true`, suppresses non-error build output. Useful in CI pipelines where
-you only want to see errors.
+When `true`, suppresses non-error build output. Handy in CI pipelines where you only want to see errors.
 
 ```typescript
 build: {
@@ -192,7 +213,7 @@ Configure validation behavior.
 | `maxBundleSize` | `string` | `undefined` | Maximum bundle size (e.g., "5mb") |
 | `strict` | `boolean` | `undefined` | Treat warnings as errors |
 
-#### Set Bundle Size Limit
+#### Set bundle size limit
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -205,7 +226,7 @@ export default GitHubAction.create({
 });
 ```
 
-#### Skip action.yml Validation
+#### Skip action.yml validation
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -217,7 +238,7 @@ export default GitHubAction.create({
 });
 ```
 
-#### Validation Options Details
+#### Validation options details
 
 ##### requireActionYml
 
@@ -233,8 +254,7 @@ validation: {
 
 ##### maxBundleSize
 
-Set a maximum bundle size. If the bundle exceeds this limit, validation fails.
-Useful for keeping actions fast to download.
+Set a maximum bundle size. Validation fails if the bundle exceeds the limit, which keeps the action fast to download.
 
 Supported units:
 
@@ -265,8 +285,7 @@ validation: {
 
 ### persistLocal
 
-Configure automatic persistence of build output to a local action directory
-for testing with [nektos/act](https://github.com/nektos/act).
+Configure automatic persistence of build output to a local action directory for testing with [nektos/act](https://github.com/nektos/act).
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -274,14 +293,11 @@ for testing with [nektos/act](https://github.com/nektos/act).
 | `path` | `string` | `".github/actions/local"` | Output directory relative to project root |
 | `actTemplate` | `boolean` | `true` | Generate act boilerplate files if they don't exist |
 
-#### Default Behavior
+#### Default behavior
 
-With no configuration, `persistLocal` is enabled. After each build, the builder
-copies `action.yml` and `dist/` to `.github/actions/local/` and generates act
-template files (`.actrc` and `.github/workflows/act-test.yml`) if they do not
-already exist.
+With no configuration, `persistLocal` is enabled. After each build, the builder copies `action.yml` and `dist/` to `.github/actions/local/` and generates act template files (`.actrc` and `.github/workflows/act-test.yml`) if they do not already exist.
 
-#### Custom Output Path
+#### Custom output path
 
 ```typescript
 import { defineConfig } from "@savvy-web/github-action-builder";
@@ -293,7 +309,7 @@ export default defineConfig({
 });
 ```
 
-#### Disable Persist Local
+#### Disable persist local
 
 ```typescript
 import { defineConfig } from "@savvy-web/github-action-builder";
@@ -305,13 +321,11 @@ export default defineConfig({
 });
 ```
 
-#### Persist Local Options Details
+#### Persist local options details
 
 ##### enabled
 
-When `true` (default), the builder copies `action.yml` and the `dist/`
-directory to the local action path after every successful build. Uses hash-based
-comparison to skip unchanged files and removes stale files from the destination.
+When `true` (default), the builder copies `action.yml` and the `dist/` directory to the local action path after every successful build. Uses hash-based comparison to skip unchanged files and removes stale files from the destination.
 
 Disable to skip local persistence entirely:
 
@@ -321,13 +335,11 @@ persistLocal: {
 }
 ```
 
-You can also skip persistence for a single build using the `--no-persist` CLI
-flag without changing your configuration.
+You can also skip persistence for a single build using the `--no-persist` CLI flag without changing your configuration.
 
 ##### path
 
-The output directory for the local action, relative to the project root.
-Defaults to `".github/actions/local"`.
+The output directory for the local action, relative to the project root. Defaults to `".github/actions/local"`.
 
 The directory is created automatically if it does not exist.
 
@@ -339,14 +351,12 @@ persistLocal: {
 
 ##### actTemplate
 
-When `true` (default), the builder generates act boilerplate files if they do
-not already exist:
+When `true` (default), the builder generates act boilerplate files when they do not already exist:
 
 * `.actrc` - Default act options
 * `.github/workflows/act-test.yml` - Minimal workflow for local testing
 
-Existing files are never overwritten. Set to `false` if you manage these files
-yourself:
+Existing files are never overwritten. Set to `false` if you manage these files yourself:
 
 ```typescript
 persistLocal: {
@@ -354,10 +364,9 @@ persistLocal: {
 }
 ```
 
-For a detailed guide on local testing with act, see
-[Local Testing](./local-testing.md).
+For a detailed guide on local testing with act, see [Local testing](./03-local-testing.md).
 
-## Full Configuration Example
+## Full configuration example
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -376,6 +385,7 @@ export default GitHubAction.create({
     target: "es2022",
     sourceMap: false,
     externals: [],
+    ignore: [],
     quiet: false,
   },
 
@@ -395,7 +405,7 @@ export default GitHubAction.create({
 });
 ```
 
-## Zero Configuration
+## Zero configuration
 
 The builder works without any configuration file. These defaults are applied:
 
@@ -410,6 +420,7 @@ The builder works without any configuration file. These defaults are applied:
     target: "es2022",
     sourceMap: false,
     externals: [],
+    ignore: [],
     quiet: false,
   },
   validation: {
@@ -424,7 +435,7 @@ The builder works without any configuration file. These defaults are applied:
 }
 ```
 
-## Config File Location
+## Config file location
 
 The builder looks for configuration in this order:
 
@@ -433,11 +444,9 @@ The builder looks for configuration in this order:
 3. `action.config.js` in the current directory
 4. `action.config.mjs` in the current directory
 
-TypeScript config files (`.ts`) are loaded using
-[jiti](https://github.com/unjs/jiti), so they work in any environment including
-CI runners without a TypeScript loader registered.
+TypeScript config files (`.ts`) are loaded with [jiti](https://github.com/unjs/jiti), so they work on CI runners that have no TypeScript loader registered.
 
-## Shared TypeScript Configuration
+## Shared TypeScript configuration
 
 The package exports a base `tsconfig.json` for GitHub Action projects:
 
@@ -447,17 +456,16 @@ The package exports a base `tsconfig.json` for GitHub Action projects:
 }
 ```
 
-This includes sensible defaults for Node.js 24 ESM actions:
+It sets the defaults Node.js 24 ESM actions need:
 
 * `target`: ES2022
 * `module`: ESNext with bundler resolution
 * `strict`: enabled
-* Includes patterns for `src/`, `lib/`, `__test__/`, `types/`, and root-level
-  TypeScript files (covers `action.config.ts`)
+* Includes patterns for `src/`, `lib/`, `__test__/`, `types/`, and root-level TypeScript files (covers `action.config.ts`)
 
 Override any setting in your project's `tsconfig.json` as needed.
 
-## Programmatic Configuration
+## Programmatic configuration
 
 When using the programmatic API, pass configuration directly:
 
@@ -484,8 +492,8 @@ const action = GitHubAction.create({
 });
 ```
 
-## Related Documentation
+## Related documentation
 
-* [CLI Reference](./cli-reference.md) - Command-line options
-* [Getting Started](./getting-started.md) - Project setup
-* [Troubleshooting](./troubleshooting.md) - Common issues
+* [CLI reference](./04-cli-reference.md) - Command-line options
+* [Getting started](./01-getting-started.md) - Project setup
+* [Troubleshooting](./06-troubleshooting.md) - Common issues
diff --git a/docs/local-testing.md b/docs/03-local-testing.md
similarity index 66%
rename from docs/local-testing.md
rename to docs/03-local-testing.md
index 72ae467..532d23d 100644
--- a/docs/local-testing.md
+++ b/docs/03-local-testing.md
@@ -1,18 +1,12 @@
-# Local Testing
+# Local testing
 
-This guide explains how to test your GitHub Action locally using the
-`persistLocal` feature and [nektos/act](https://github.com/nektos/act).
+This guide explains how to test your GitHub Action locally using the `persistLocal` feature and [nektos/act](https://github.com/nektos/act).
 
-## Why Local Testing?
+## Why local testing?
 
-GitHub's `node24` runtime prevents repositories from running their own compiled
-`pre.js` scripts when referencing the action with `uses: ./`. The runner
-expects the action to live in a subdirectory under `.github/actions/` rather
-than in the repository root. The `persistLocal` feature solves this by
-automatically copying your build output to a local action directory where act
-can find and execute it.
+GitHub's `node24` runtime will not run a repository's own compiled `pre.js` scripts when the action is referenced with `uses: ./`. The runner expects the action to live in a subdirectory under `.github/actions/`, not in the repository root. `persistLocal` works around this: after every build it copies your output to a local action directory where act can find it.
 
-## What persistLocal Does
+## What persistLocal does
 
 After each successful build, the builder:
 
@@ -20,7 +14,7 @@ After each successful build, the builder:
 2. Copies the entire `dist/` directory to `.github/actions/local/dist/`
 3. Generates act template files if they do not already exist
 
-The result is a self-contained action directory that act can reference directly.
+The result is a complete action directory that act can reference directly.
 
 ```text
 .github/actions/local/
@@ -32,19 +26,17 @@ The result is a self-contained action directory that act can reference directly.
     └── package.json
 ```
 
-## Smart Sync
+## How files are synced
 
-The builder uses hash-based comparison when syncing files:
+The builder compares file hashes before it writes anything:
 
 * **Changed files** are copied to the destination
-* **Unchanged files** are skipped (no unnecessary writes)
-* **Stale files** in the destination that no longer exist in the source are
-  removed
+* **Unchanged files** are skipped — no write happens
+* **Stale files** that exist in the destination but no longer exist in the source are removed
 
-This keeps the local action directory in sync with your build output without
-redundant file operations.
+So the local action directory always matches your latest build, and a build that changed nothing copies nothing.
 
-## Getting Started with act
+## Getting started with act
 
 ### Prerequisites
 
@@ -57,7 +49,7 @@ brew install act
 # Other platforms: see https://nektosact.com/installation/
 ```
 
-### First Run
+### First run
 
 Build your action and run it locally:
 
@@ -98,10 +90,9 @@ jobs:
 
 This workflow references your local action directory so act can execute it.
 
-### Customizing the Test Workflow
+### Customizing the test workflow
 
-The generated `act-test.yml` is a minimal starting point. Edit it to match your
-action's inputs and test scenarios:
+The generated `act-test.yml` is a minimal starting point. Edit it to match your action's inputs and test scenarios:
 
 ```yaml
 name: Local Test
@@ -117,8 +108,7 @@ jobs:
           example-input: "test value"
 ```
 
-The builder never overwrites existing template files, so your customizations
-are preserved.
+The builder never overwrites a template file that already exists, so it leaves your edits alone.
 
 ## Configuration
 
@@ -142,11 +132,11 @@ export default defineConfig({
 | `path` | `string` | `".github/actions/local"` | Output directory relative to project root |
 | `actTemplate` | `boolean` | `true` | Generate act boilerplate files if missing |
 
-For full details on each option, see [Configuration](./configuration.md).
+For full details on each option, see [Configuration](./02-configuration.md).
 
-## CLI Usage
+## CLI usage
 
-### Skip Persistence
+### Skip persistence
 
 Use `--no-persist` to skip the persist step for a single build:
 
@@ -154,10 +144,9 @@ Use `--no-persist` to skip the persist step for a single build:
 github-action-builder build --no-persist
 ```
 
-This is useful when you want a fast build without updating the local action
-directory, for example during rapid iteration on source code.
+Use it while iterating on source code, when you want a quick build and do not need the local action directory refreshed.
 
-### Typical Development Workflow
+### Typical development workflow
 
 ```bash
 # Edit source code
@@ -174,8 +163,7 @@ act
 
 ## Programmatic API
 
-When using the programmatic API, the build result includes a `persistLocal`
-field with details about the persist operation:
+When using the programmatic API, the build result includes a `persistLocal` field with details about the persist operation:
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -187,6 +175,9 @@ if (result.success && result.persistLocal) {
   console.log(`Output: ${result.persistLocal.outputPath}`);
   console.log(`Files copied: ${result.persistLocal.filesCopied}`);
   console.log(`Files skipped: ${result.persistLocal.filesSkipped}`);
+  // Output: /path/to/project/.github/actions/local
+  // Files copied: <count of new or changed files>
+  // Files skipped: <count of unchanged files>
 }
 ```
 
@@ -203,8 +194,7 @@ The `persistLocal` result contains:
 
 ## Disabling persistLocal
 
-To disable local persistence entirely, set `enabled` to `false` in your
-configuration:
+To disable local persistence entirely, set `enabled` to `false` in your configuration:
 
 ```typescript
 import { defineConfig } from "@savvy-web/github-action-builder";
@@ -216,13 +206,11 @@ export default defineConfig({
 });
 ```
 
-When disabled, the builder skips the persist step completely and does not
-generate any template files.
+When disabled, the builder skips the persist step completely and does not generate any template files.
 
-## Git Ignore
+## Git ignore
 
-You may want to add the local action directory and act configuration to your
-`.gitignore`:
+You may want to add the local action directory and act configuration to your `.gitignore`:
 
 ```text
 # Local testing
@@ -230,12 +218,11 @@ You may want to add the local action directory and act configuration to your
 .actrc
 ```
 
-Alternatively, commit the local action directory if you want CI to be able to
-reference it directly.
+Alternatively, commit the local action directory if you want CI to be able to reference it directly.
 
-## Related Documentation
+## Related documentation
 
-* [Configuration](./configuration.md) - All configuration options
-* [CLI Reference](./cli-reference.md) - Command reference
-* [Getting Started](./getting-started.md) - Project setup
-* [Troubleshooting](./troubleshooting.md) - Common issues
+* [Configuration](./02-configuration.md) - All configuration options
+* [CLI reference](./04-cli-reference.md) - Command reference
+* [Getting started](./01-getting-started.md) - Project setup
+* [Troubleshooting](./06-troubleshooting.md) - Common issues
diff --git a/docs/cli-reference.md b/docs/04-cli-reference.md
similarity index 84%
rename from docs/cli-reference.md
rename to docs/04-cli-reference.md
index 0eb84d8..130cd0a 100644
--- a/docs/cli-reference.md
+++ b/docs/04-cli-reference.md
@@ -1,4 +1,4 @@
-# CLI Reference
+# CLI reference
 
 Complete reference for the `github-action-builder` command-line interface.
 
@@ -67,9 +67,9 @@ Build without persisting locally:
 github-action-builder build --no-persist
 ```
 
-**Build Process:**
+**Build process:**
 
-The build command:
+`build` runs four steps in order:
 
 1. Loads configuration from `action.config.ts` (or defaults)
 2. Validates the project (unless `--no-validate`)
@@ -88,15 +88,15 @@ Validating...
 Building...
 
 Build Summary:
-  main: 89.2 KB (1234ms) -> dist/main.js
-  post: 12.5 KB (567ms) -> dist/post.js
+  main: <size> (<time>) -> dist/main.js
+  post: <size> (<time>) -> dist/post.js
 
-Total time: 1801ms
+Total time: <total>
 
 Build completed successfully!
 ```
 
-**Exit Codes:**
+**Exit codes:**
 
 | Code | Meaning |
 | --- | --- |
@@ -134,15 +134,15 @@ Validate with custom config:
 github-action-builder validate --config ./my-config.ts
 ```
 
-**What Gets Validated:**
+**What gets validated:**
 
-The validate command checks:
+`validate` checks three things:
 
 1. **Configuration**
    * Config file syntax (if provided)
    * Schema validation for all options
 
-2. **Entry Points**
+2. **Entry points**
    * `src/main.ts` exists (required)
    * `src/pre.ts` exists (if configured)
    * `src/post.ts` exists (if configured)
@@ -153,7 +153,7 @@ The validate command checks:
    * Matches GitHub's action metadata schema
    * `runs.using` is set to `node24`
 
-**Validation Output:**
+**Validation output:**
 
 Example validation output:
 
@@ -186,7 +186,7 @@ Validation Results:
 Validation failed with 2 errors
 ```
 
-**Exit Codes:**
+**Exit codes:**
 
 | Code | Meaning |
 | --- | --- |
@@ -195,7 +195,7 @@ Validation failed with 2 errors
 
 ## github-action-builder init
 
-Create a new GitHub Action project with all required files.
+Create a new GitHub Action project, including every file the action needs to build.
 
 **Usage:**
 
@@ -220,8 +220,8 @@ github-action-builder init <action-name> [options]
 Create a new action project:
 
 ```bash
-npx @savvy-web/github-action-builder init my-awesome-action
-cd my-awesome-action
+npx @savvy-web/github-action-builder init my-action
+cd my-action
 npm install
 npm run build
 ```
@@ -232,9 +232,9 @@ Overwrite existing files:
 github-action-builder init my-action --force
 ```
 
-**Generated Files:**
+**Generated files:**
 
-The init command creates a complete project structure:
+`init` writes this project structure:
 
 ```text
 my-action/
@@ -293,7 +293,7 @@ export default GitHubAction.create({
 });
 ```
 
-**Init Output:**
+**Init output:**
 
 ```text
 Created my-action/
@@ -311,14 +311,14 @@ Next steps:
   npm run build
 ```
 
-**Exit Codes:**
+**Exit codes:**
 
 | Code | Meaning |
 | --- | --- |
 | `0` | Project created successfully |
 | `1` | Directory exists (use `--force`) |
 
-## Global Options
+## Global options
 
 These options work with all commands:
 
@@ -340,24 +340,20 @@ github-action-builder build --help
 github-action-builder --version
 ```
 
-## Environment Variables
+## Environment variables
 
-The CLI respects these environment variables:
+Two environment variables change CLI behavior:
 
 | Variable | Effect |
 | --- | --- |
 | `CI=true` | Enables strict mode (warnings become errors) |
 | `GITHUB_ACTIONS=true` | Enables strict mode |
 
-### CI Detection
+### CI detection
 
-In CI environments, the builder automatically enables strict mode:
+When `CI` or `GITHUB_ACTIONS` is set, the builder switches on strict mode: validation warnings are treated as errors and the build fails on any issue. This stops a marginal action.yml from shipping just because no human watched the log.
 
-* Validation warnings become errors
-* Build fails on any issue
-* Ensures quality gates in CI pipelines
-
-Override with the `strict` configuration option:
+To opt out, set the `strict` configuration option:
 
 ```typescript
 // action.config.ts
@@ -368,9 +364,9 @@ export default defineConfig({
 });
 ```
 
-## Using with npm Scripts
+## Using with npm scripts
 
-Add scripts to your `package.json`:
+Wire the commands into `package.json`:
 
 ```json
 {
@@ -399,8 +395,8 @@ npx @savvy-web/github-action-builder validate
 npx @savvy-web/github-action-builder init
 ```
 
-## Related Documentation
+## Related documentation
 
-* [Configuration](./configuration.md) - All configuration options
-* [Getting Started](./getting-started.md) - Project setup
-* [Troubleshooting](./troubleshooting.md) - Common issues
+* [Configuration](./02-configuration.md) - All configuration options
+* [Getting started](./01-getting-started.md) - Project setup
+* [Troubleshooting](./06-troubleshooting.md) - Common issues
diff --git a/docs/architecture.md b/docs/05-architecture.md
similarity index 84%
rename from docs/architecture.md
rename to docs/05-architecture.md
index eb9926e..fa13621 100644
--- a/docs/architecture.md
+++ b/docs/05-architecture.md
@@ -1,12 +1,10 @@
 # Architecture
 
-This guide explains how `@savvy-web/github-action-builder` works internally.
-It is intended for advanced users who want to understand the design, extend the
-tool, or contribute to development.
+This guide explains how `@savvy-web/github-action-builder` works internally. Read it if you want to extend the tool or contribute to it.
 
 ## Overview
 
-The builder uses a layered architecture based on Effect-TS:
+The builder has three layers, built on Effect-TS:
 
 ```text
 +---------------------------------------------------------------+
@@ -39,19 +37,19 @@ The builder uses a layered architecture based on Effect-TS:
 
 ## Why Effect-TS?
 
-The builder uses Effect-TS for:
+Effect-TS earns its place here for a few concrete reasons:
 
-* **Type-safe error handling** - Errors are tracked in the type system
-* **Dependency injection** - Services are composed via Layers
-* **Testability** - Mock services can be injected for testing
-* **Resource safety** - File handles and processes are properly managed
-* **Composability** - Complex workflows built from simple operations
+* **Type-safe error handling** - every failure mode shows up in the type signature, so you cannot forget to handle one
+* **Dependency injection** - services compose through Layers instead of imports
+* **Testability** - swap in a mock service by providing a different Layer
+* **Resource safety** - file handles and child processes close even when a build throws
+* **Composability** - the build pipeline is a few small Effects chained together
 
-## Service Layer
+## Service layer
 
 ### ConfigService
 
-Handles configuration loading and entry point detection.
+Loads configuration and finds entry points.
 
 ```typescript
 interface ConfigService {
@@ -101,7 +99,7 @@ interface ValidationService {
 
 ### BuildService
 
-Bundles TypeScript entry points with `@rsbuild/core` (rspack-based).
+Bundles TypeScript entry points with `@rsbuild/core`, which runs on rspack.
 
 ```typescript
 interface BuildService {
@@ -121,15 +119,15 @@ interface BuildService {
 
 **Key behaviors:**
 
-* Cleans `dist/` directory before building (configurable)
+* Cleans `dist/` before building, unless you turn that off in config
 * Bundles each detected entry point with rsbuild (rspack)
 * Writes `dist/package.json` with `{ "type": "module" }`
-* Produces clean ESM output without eval("require") hacks
-* Supports tree-shaking via rspack, `node:` builtins externalized
+* Emits plain ESM, with no `eval("require")` hacks
+* Tree-shakes through rspack and externalizes `node:` builtins
 
-## Layer Composition
+## Layer composition
 
-Services are composed using Effect Layers:
+Effect Layers wire the services together:
 
 ```typescript
 // Individual service layers
@@ -149,9 +147,9 @@ export const AppLayer = Layer.mergeAll(
 );
 ```
 
-The `AppLayer` provides all services needed to run the CLI or programmatic API.
+`AppLayer` carries every service the CLI and the programmatic API need.
 
-## Build Pipeline
+## Build pipeline
 
 ```text
 +----------+    +----------+    +----------+    +----------+
@@ -164,14 +162,14 @@ ConfigService   ConfigService  ValidationService  BuildService
   .load()       .detectEntries()  .validate()      .build()
 ```
 
-### Stage 1: Load Configuration
+### Stage 1: Load configuration
 
 1. Check for `action.config.ts` or use `--config` path
 2. Dynamically import the TypeScript config
 3. Validate against `ConfigSchema`
 4. Apply defaults for missing options
 
-### Stage 2: Detect Entry Points
+### Stage 2: Detect entry points
 
 1. Check for required `src/main.ts`
 2. Check for optional `src/pre.ts` and `src/post.ts`
@@ -193,9 +191,9 @@ ConfigService   ConfigService  ValidationService  BuildService
 4. Create `dist/package.json`
 5. Report statistics
 
-## Error Handling
+## Error handling
 
-All errors use Effect's `Data.TaggedError` pattern:
+Every error is a `Data.TaggedError` subclass:
 
 ```typescript
 // Define error types
@@ -216,7 +214,7 @@ Effect.gen(function* () {
 );
 ```
 
-### Error Categories
+### Error categories
 
 **Config Errors:**
 
@@ -240,9 +238,9 @@ Effect.gen(function* () {
 * `CleanError` - Failed to clean output directory
 * `BuildFailed` - Overall build process failed
 
-## Schema Validation
+## Schema validation
 
-All schemas use `@effect/schema`:
+Schemas are defined with `@effect/schema`:
 
 ```typescript
 const ConfigSchema = Schema.Struct({
@@ -265,9 +263,9 @@ const ActionYml = Schema.Struct({
 
 ## Programmatic API
 
-### GitHubAction Class
+### GitHubAction class
 
-The `GitHubAction` class wraps Effect services for non-Effect consumers:
+If your code does not use Effect, the `GitHubAction` class wraps the services behind plain Promises:
 
 ```typescript
 class GitHubAction {
@@ -282,7 +280,7 @@ class GitHubAction {
 }
 ```
 
-It uses `ManagedRuntime` to execute Effects as Promises:
+A `ManagedRuntime` runs each Effect and hands back a Promise:
 
 ```typescript
 async build(): Promise<GitHubActionBuildResult> {
@@ -294,9 +292,9 @@ async build(): Promise<GitHubActionBuildResult> {
 }
 ```
 
-### Using Services Directly
+### Using services directly
 
-Effect consumers can use services directly:
+If your code already uses Effect, skip the wrapper and pull the services straight from the context:
 
 ```typescript
 import { Effect } from "effect";
@@ -315,9 +313,9 @@ const program = Effect.gen(function* () {
 Effect.runPromise(program.pipe(Effect.provide(AppLayer)));
 ```
 
-### Custom Layers
+### Custom layers
 
-Inject custom implementations for testing:
+To test against a fake build, pass your own Layer:
 
 ```typescript
 import { GitHubAction } from "@savvy-web/github-action-builder";
@@ -332,7 +330,7 @@ const action = GitHubAction.create({
 });
 ```
 
-## File Structure
+## File structure
 
 ```text
 src/
@@ -360,7 +358,7 @@ src/
         +-- init.ts          # Init command handler
 ```
 
-## Design Decisions
+## Design decisions
 
 | Decision | Rationale |
 | --- | --- |
@@ -373,9 +371,9 @@ src/
 | Flat output structure | Simple, no nested directories |
 | CI-aware strict mode | Fast dev feedback, strict CI gates |
 
-## Extending the Builder
+## Extending the builder
 
-### Adding a New Service
+### Adding a new service
 
 1. Define the service interface in `services/`:
 
@@ -406,7 +404,7 @@ export const AppLayer = Layer.mergeAll(
 );
 ```
 
-### Adding a New Command
+### Adding a new command
 
 1. Create command in `cli/commands/`:
 
@@ -428,8 +426,8 @@ const rootCommand = Command.make("github-action-builder").pipe(
 );
 ```
 
-## Related Documentation
+## Related documentation
 
-* [Configuration](./configuration.md) - Configuration options
-* [CLI Reference](./cli-reference.md) - Command reference
-* [Troubleshooting](./troubleshooting.md) - Common issues
+* [Configuration](./02-configuration.md) - Configuration options
+* [CLI reference](./04-cli-reference.md) - Command reference
+* [Troubleshooting](./06-troubleshooting.md) - Common issues
diff --git a/docs/troubleshooting.md b/docs/06-troubleshooting.md
similarity index 84%
rename from docs/troubleshooting.md
rename to docs/06-troubleshooting.md
index 3a2a649..cc16980 100644
--- a/docs/troubleshooting.md
+++ b/docs/06-troubleshooting.md
@@ -1,8 +1,8 @@
 # Troubleshooting
 
-Solutions to common issues when using `@savvy-web/github-action-builder`.
+Common errors from `@savvy-web/github-action-builder`, what causes them and how to fix them.
 
-## Validation Errors
+## Validation errors
 
 ### "runs.using must be 'node24'"
 
@@ -22,8 +22,7 @@ runs:
   main: "dist/main.js"
 ```
 
-This builder only supports Node.js 24 actions. If you need to support older
-Node.js versions, use a different build tool.
+This builder targets Node.js 24 actions only. For older Node.js versions, use a different build tool.
 
 ### "Required entry not found: src/main.ts"
 
@@ -129,7 +128,7 @@ for required fields:
 - `runs.using` (required, must be `node24`)
 - `runs.main` (required)
 
-## Build Errors
+## Build errors
 
 ### "Bundle failed"
 
@@ -235,7 +234,7 @@ Clean error: ENOTEMPTY: directory not empty
 
 3. Run the build again
 
-## Configuration Errors
+## Configuration errors
 
 ### "Config not found"
 
@@ -271,8 +270,7 @@ Config invalid: /build/target: Expected one of "es2020" | "es2021" | ...
 
 **Cause:** Your configuration has invalid values.
 
-**Solution:** Check the [Configuration](./configuration.md) guide for valid
-options. Common issues:
+**Solution:** Check the [Configuration](./02-configuration.md) guide for valid options. Common issues:
 
 - Invalid `target` value (must be `es2020`-`es2024`)
 - Wrong type (e.g., string instead of boolean)
@@ -307,29 +305,17 @@ Config load failed: Cannot find module '@savvy-web/github-action-builder'
 ConfigLoadFailed: Unknown file extension ".ts" for /path/to/action.config.ts
 ```
 
-**Cause:** This occurred in versions prior to 0.6.0 where `action.config.ts`
-was loaded via native `import()`, which requires a TypeScript loader registered
-in the Node.js runtime. CI environments typically do not have one.
+**Cause:** Versions prior to 0.6.0 loaded `action.config.ts` through native `import()`. That needs a TypeScript loader registered in the Node.js runtime, and CI environments usually do not have one.
 
-**Solution:** Upgrade to `@savvy-web/github-action-builder@0.6.0` or later,
-which uses [jiti](https://github.com/unjs/jiti) to load TypeScript config files
-without requiring an external loader.
+**Solution:** Upgrade to `@savvy-web/github-action-builder@0.6.0` or later. Recent versions load TypeScript config files with [jiti](https://github.com/unjs/jiti), so no external loader is needed.
 
-## CI vs Local Differences
+## CI vs local differences
 
 ### "Build fails in CI but works locally"
 
 **Cause:** CI uses strict mode by default.
 
-**Explanation:** In CI environments (`CI=true` or `GITHUB_ACTIONS=true`):
-
-- Warnings become errors
-- Build fails on any issue
-
-Locally:
-
-- Warnings are displayed but build continues
-- Faster iteration during development
+**Explanation:** In CI environments (`CI=true` or `GITHUB_ACTIONS=true`) warnings become errors and the build fails on any issue. Locally, warnings are printed but the build continues, so you can keep iterating.
 
 **Solution:**
 
@@ -356,7 +342,7 @@ Locally:
 2. Use a lockfile (`package-lock.json`, `pnpm-lock.yaml`)
 3. Run `npm ci` instead of `npm install` in CI
 
-## Node.js 24 Compatibility
+## Node.js 24 compatibility
 
 ### "Node.js version not supported"
 
@@ -424,21 +410,20 @@ SyntaxError: Cannot use import statement outside a module
    }
    ```
 
-## Getting Help
+## Getting help
 
 If your issue is not covered here:
 
-1. Check the [GitHub Issues](https://github.com/savvy-web/github-action-builder/issues)
-   for similar problems
-2. Create a new issue with:
+1. Search the [GitHub Issues](https://github.com/savvy-web/github-action-builder/issues) for a similar problem
+2. If you find nothing, open a new issue with:
    - Error message (full output)
    - Your `action.config.ts`
    - Your `action.yml`
    - Node.js version (`node --version`)
    - Package version (`npm list @savvy-web/github-action-builder`)
 
-## Related Documentation
+## Related documentation
 
-- [Configuration](./configuration.md) - All configuration options
-- [CLI Reference](./cli-reference.md) - Command reference
-- [Getting Started](./getting-started.md) - Project setup
+- [Configuration](./02-configuration.md) - Every configuration option
+- [CLI reference](./04-cli-reference.md) - Every command and flag
+- [Getting started](./01-getting-started.md) - Project setup from scratch
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..511c286
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,12 @@
+# @savvy-web/github-action-builder documentation
+
+A zero-config build tool for creating GitHub Actions from TypeScript source code. These pages cover setup, configuration, local testing, the CLI and the internals.
+
+## Pages
+
+- [Getting started](./01-getting-started.md) — Build your first GitHub Action, start to finish.
+- [Configuration](./02-configuration.md) — Every option you can pass to `defineConfig`.
+- [Local testing](./03-local-testing.md) — Run your action on your machine with `persistLocal` and nektos/act.
+- [CLI reference](./04-cli-reference.md) — Every flag and subcommand of the `github-action-builder` command.
+- [Architecture](./05-architecture.md) — How the builder works under the hood.
+- [Troubleshooting](./06-troubleshooting.md) — Fixes for the problems people hit most often.
diff --git a/docs/superpowers/plans/2026-03-19-replace-ncc-with-rsbuild.md b/docs/superpowers/plans/2026-03-19-replace-ncc-with-rsbuild.md
deleted file mode 100644
index 5c28d16..0000000
--- a/docs/superpowers/plans/2026-03-19-replace-ncc-with-rsbuild.md
+++ /dev/null
@@ -1,524 +0,0 @@
-# Replace ncc with Rsbuild Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace `@vercel/ncc` with `@rsbuild/core` for GitHub Action bundling while keeping the same external API.
-
-**Architecture:** Swap the bundler implementation inside `BuildServiceLive` (specifically the `bundleEntry()` function). Simplify the config schema by removing ncc-specific options (`target`, `quiet`). The service interface, Layer composition, CLI, and public API are untouched.
-
-**Tech Stack:** `@rsbuild/core`, Effect-TS, Vitest
-
-**Spec:** `docs/superpowers/specs/2026-03-19-replace-ncc-with-rsbuild-design.md`
-
----
-
-## File Map
-
-| Action | File | Responsibility |
-| ------ | ---- | -------------- |
-| Modify | `package.json` | Swap `@vercel/ncc` for `@rsbuild/core`, update description/keywords |
-| Modify | `src/schemas/config.ts` | Remove `target`, `quiet`, `EsTarget` from schema |
-| Modify | `src/schemas/config.test.ts` | Update tests for removed fields |
-| Modify | `src/index.ts` | Remove `EsTarget` type export, update module JSDoc |
-| Modify | `src/index.test.ts` | Update defineConfig assertions |
-| Modify | `src/services/build-live.ts` | Replace ncc with rsbuild in `bundleEntry()` |
-| Modify | `src/services/build.ts` | Update JSDoc only |
-| Modify | `src/errors.ts` | Update `BundleFailed` JSDoc only |
-| Modify | `src/github-action.ts` | Update docstring examples and ncc references |
-| Modify | `src/cli/commands/init.ts` | Update template config |
-
----
-
-## Task 1: Swap dependencies
-
-**Files:**
-
-- Modify: `package.json:62-72`
-
-- [ ] **Step 1: Remove @vercel/ncc and add @rsbuild/core**
-
-```bash
-pnpm remove @vercel/ncc && pnpm add @rsbuild/core
-```
-
-- [ ] **Step 2: Verify install succeeded**
-
-```bash
-pnpm ls @rsbuild/core
-```
-
-Expected: Shows `@rsbuild/core` with version in output.
-
-- [ ] **Step 3: Update package.json description and keywords**
-
-In `package.json`:
-
-- Line 5: Update `description` — replace `@vercel/ncc` with `rsbuild`
-- Lines 10-11: In `keywords` array, replace `"ncc"` and `"vercel-ncc"` with
-  `"rsbuild"` and `"rspack"`
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add package.json pnpm-lock.yaml
-git commit -m "feat(deps): replace @vercel/ncc with @rsbuild/core
-
-Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>"
-```
-
----
-
-## Task 2: Simplify config schema
-
-**Files:**
-
-- Modify: `src/schemas/config.ts:47-81` (BuildOptionsSchema, EsTarget)
-- Modify: `src/schemas/config.ts:161-192` (ConfigInputSchema)
-- Modify: `src/schemas/config.ts:261-284` (defineConfig example)
-- Modify: `src/index.ts:63-80` (remove EsTarget export)
-
-- [ ] **Step 1: Write failing tests for new schema shape**
-
-In `src/schemas/config.test.ts`, update the BuildOptions tests. The new defaults
-should have only `minify`, `sourceMap`, and `externals` — no `target` or `quiet`.
-
-Update the `"applies defaults when decoding empty object"` test (around line 50):
-remove assertions for `target` and `quiet`, keep `minify`, `sourceMap`,
-`externals`.
-
-```typescript
-it("applies defaults when decoding empty object", () => {
-  const options = Schema.decodeUnknownSync(BuildOptionsSchema)({});
-  expect(options.minify).toBe(true);
-  expect(options.sourceMap).toBe(false);
-  expect(options.externals).toEqual([]);
-});
-```
-
-Update the `"accepts custom options"` test (around line 59): remove `target` and
-`quiet` from input and assertions.
-
-```typescript
-it("accepts custom options", () => {
-  const options = Schema.decodeUnknownSync(BuildOptionsSchema)({
-    minify: false,
-    sourceMap: true,
-    externals: ["@aws-sdk/client-s3"],
-  });
-  expect(options.minify).toBe(false);
-  expect(options.sourceMap).toBe(true);
-  expect(options.externals).toEqual(["@aws-sdk/client-s3"]);
-});
-```
-
-Update the `"decodes from plain object"` test (around line 74): remove the
-`target` assertion at line 79.
-
-Remove the entire `"EsTarget Literal"` describe block (around lines 123-137).
-
-Update the `"ConfigInput Schema"` describe block (around lines 156-164): remove
-`target: "es2023"` from the input object (line 159) and
-`expect(decoded.build?.target).toBe("es2023")` assertion (line 163).
-
-Update the `"merges partial config with defaults"` test in the `defineConfig`
-describe block: remove `expect(config.build.target).toBe("es2022")` (around
-line 207).
-
-Update the `"handles all build options"` test (around line 223): remove `target`
-and `quiet` from input and assertions.
-
-```typescript
-it("handles all build options", () => {
-  const config = defineConfig({
-    entries: { main: "src/action.ts", pre: "src/pre.ts", post: "src/post.ts" },
-    build: {
-      minify: false,
-      sourceMap: true,
-      externals: ["some-external"],
-    },
-    validation: { requireActionYml: false, maxBundleSize: "5mb", strict: true },
-  });
-  expect(config.build.minify).toBe(false);
-  expect(config.build.sourceMap).toBe(true);
-  expect(config.build.externals).toEqual(["some-external"]);
-});
-```
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-```bash
-pnpm vitest run src/schemas/config.test.ts -v
-```
-
-Expected: Failures due to `target` and `quiet` still in schema.
-
-- [ ] **Step 3: Update BuildOptionsSchema**
-
-In `src/schemas/config.ts`, remove `EsTarget` (lines 47-59) and simplify
-`BuildOptionsSchema` (lines 70-81):
-
-```typescript
-export const BuildOptionsSchema = Schema.Struct({
-  /** Enable minification to reduce bundle size. Defaults to true. */
-  minify: Schema.optionalWith(Schema.Boolean, { default: () => true }),
-  /** Generate source maps for debugging. Defaults to false. */
-  sourceMap: Schema.optionalWith(Schema.Boolean, { default: () => false }),
-  /** Packages to exclude from the bundle (in addition to node: builtins). Defaults to []. */
-  externals: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
-});
-```
-
-- [ ] **Step 4: Update ConfigInputSchema**
-
-In `src/schemas/config.ts`, update the `build` field in `ConfigInputSchema`
-(lines 169-177):
-
-```typescript
-build: Schema.optional(
-  Schema.Struct({
-    minify: Schema.optional(Schema.Boolean),
-    sourceMap: Schema.optional(Schema.Boolean),
-    externals: Schema.optional(Schema.Array(Schema.String)),
-  }),
-),
-```
-
-- [ ] **Step 5: Update defineConfig JSDoc example**
-
-In `src/schemas/config.ts`, update the "Full configuration" `@example` (lines
-261-284). Remove `target: "es2022"` from the build options in the example.
-
-- [ ] **Step 6: Update src/index.ts exports and JSDoc**
-
-In `src/index.ts`:
-
-- Remove `EsTarget` from the type export block (line 68).
-- Update module-level JSDoc: change `"vercel/ncc"` to `"rsbuild"` (line 10-11).
-- Update the `@example` block: remove `target: "es2022"` from build options
-  (around line 43-45).
-
-- [ ] **Step 7: Run schema tests**
-
-```bash
-pnpm vitest run src/schemas/config.test.ts -v
-```
-
-Expected: All tests pass.
-
-- [ ] **Step 8: Update index.test.ts**
-
-In `src/index.test.ts`, remove assertions for `target`:
-
-- Line 13: Remove `expect(config.build.target).toBe("es2022");`
-- Line 26: Remove `target: "es2023",` from input
-- Line 34: Remove `expect(config.build.target).toBe("es2023");`
-- Line 44: Remove `expect(config.build.target).toBe("es2022");`
-
-- [ ] **Step 9: Run all tests**
-
-```bash
-pnpm vitest run -v
-```
-
-Expected: All pass (build-live tests may fail due to ncc removal — that's
-expected and fixed in Task 3).
-
-- [ ] **Step 10: Commit**
-
-```bash
-git add src/schemas/config.ts src/schemas/config.test.ts src/index.ts src/index.test.ts
-git commit -m "feat!: remove target and quiet from BuildOptions schema
-
-BREAKING CHANGE: BuildOptions no longer accepts target or quiet fields.
-Target is hardcoded to es2024 (Node 24). The EsTarget type export is removed.
-
-Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>"
-```
-
----
-
-## Task 3: Replace ncc with rsbuild in BuildServiceLive
-
-**Files:**
-
-- Modify: `src/services/build-live.ts:1-238`
-
-- [ ] **Step 1: Replace imports and remove ncc types**
-
-Replace the top of `build-live.ts` (lines 1-64). Remove `createRequire`, all
-ncc types, and the ncc import. Add rsbuild and `statSync`:
-
-```typescript
-/* v8 ignore start - build service requires actual bundling for integration testing */
-/**
- * BuildService Layer implementation.
- *
- */
-import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { Effect, Layer } from "effect";
-
-import { createRsbuild } from "@rsbuild/core";
-
-import { BundleFailed, CleanError, WriteError } from "../errors.js";
-import type { Config } from "../schemas/config.js";
-import type { BuildResult, BuildRunnerOptions, BundleResult } from "./build.js";
-import { BuildService } from "./build.js";
-import type { DetectedEntry } from "./config.js";
-import { ConfigService } from "./config.js";
-```
-
-- [ ] **Step 2: Remove old bundle function and getBundleSize**
-
-Delete the `bundle()` function (lines 69-78) and `getBundleSize()` function
-(lines 83-85). These are replaced by rsbuild's build API and `statSync`.
-
-- [ ] **Step 3: Write new bundleEntry function**
-
-Replace the `bundleEntry()` function (lines 178-238):
-
-```typescript
-/**
- * Bundle a single entry with rsbuild.
- */
-/* v8 ignore start - bundling requires actual rsbuild execution */
-function bundleEntry(
-  entry: DetectedEntry,
-  config: Config,
-  cwd: string,
-): Effect.Effect<BundleResult, BundleFailed | WriteError> {
-  return Effect.gen(function* () {
-    const startTime = Date.now();
-    const outputDir = resolve(cwd, "dist");
-
-    // createRsbuild is synchronous — use Effect.try, not Effect.tryPromise
-    const rsbuild = yield* Effect.try({
-      try: () =>
-        createRsbuild({
-          rsbuildConfig: {
-            source: { entry: { [entry.type]: entry.path } },
-            output: {
-              target: "node",
-              module: true,
-              distPath: { root: outputDir },
-              filename: { js: "[name].js" },
-              externals: [/^node:/, ...config.build.externals],
-              minify: config.build.minify,
-              sourceMap: config.build.sourceMap
-                ? { js: "source-map" as const }
-                : false,
-            },
-            performance: {
-              chunkSplit: { strategy: "all-in-one" },
-            },
-          },
-        }),
-      catch: (error) =>
-        new BundleFailed({
-          entry: entry.path,
-          cause: error,
-        }),
-    });
-
-    const buildResult = yield* Effect.tryPromise({
-      try: () => rsbuild.build(),
-      catch: (error) =>
-        new BundleFailed({
-          entry: entry.path,
-          cause: error,
-        }),
-    });
-
-    // Release rsbuild resources (file watchers, worker threads)
-    yield* Effect.promise(() => buildResult.close());
-
-    const outputPath = resolve(outputDir, `${entry.type}.js`);
-    const size = statSync(outputPath).size;
-    const duration = Date.now() - startTime;
-
-    return {
-      success: true,
-      stats: {
-        entry: entry.type,
-        size,
-        duration,
-        outputPath: entry.output,
-      },
-    };
-  });
-}
-/* v8 ignore stop */
-```
-
-- [ ] **Step 4: Update build method references**
-
-In the `build()` method of `BuildServiceLive` (lines 258-311), no structural
-changes needed — it already calls `bundleEntry()` and handles results correctly.
-Just verify it compiles.
-
-- [ ] **Step 5: Run typecheck**
-
-```bash
-pnpm run typecheck
-```
-
-Expected: No type errors.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/services/build-live.ts
-git commit -m "feat: replace ncc with rsbuild in BuildServiceLive
-
-Replace @vercel/ncc bundling with @rsbuild/core. Uses createRsbuild()
-programmatic API with ESM output (output.module: true), single-file
-bundling (all-in-one chunk strategy), and automatic node: externalization.
-
-Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>"
-```
-
----
-
-## Task 4: Update JSDoc and template strings
-
-**Files:**
-
-- Modify: `src/errors.ts:344-349` (BundleFailed JSDoc)
-- Modify: `src/services/build.ts:108-110` (BuildService JSDoc)
-- Modify: `src/github-action.ts:154,309` (docstring example + ncc reference)
-- Modify: `src/cli/commands/init.ts:131-132` (template config)
-
-- [ ] **Step 1: Update BundleFailed JSDoc**
-
-In `src/errors.ts` line 344, change:
-
-```typescript
-/**
- * Error when bundling with ncc fails.
-```
-
-to:
-
-```typescript
-/**
- * Error when bundling with rsbuild fails.
-```
-
-- [ ] **Step 2: Update BuildService JSDoc**
-
-In `src/services/build.ts` line 110, change:
-
-```typescript
- * - Bundling TypeScript entries with vercel/ncc
-```
-
-to:
-
-```typescript
- * - Bundling TypeScript entries with rsbuild
-```
-
-- [ ] **Step 3: Update GitHubAction docstring example**
-
-In `src/github-action.ts` line 154, change:
-
-```typescript
- *       build: { minify: true, target: "es2022" },
-```
-
-to:
-
-```typescript
- *       build: { minify: true },
-```
-
-- [ ] **Step 4: Update GitHubAction ncc reference**
-
-In `src/github-action.ts` line 309, change:
-
-```typescript
- * 3. Bundles each entry point with vercel/ncc
-```
-
-to:
-
-```typescript
- * 3. Bundles each entry point with rsbuild
-```
-
-- [ ] **Step 5: Update init template**
-
-In `src/cli/commands/init.ts`, update the commented-out build options in the
-template (around line 131). Remove the `target` line:
-
-```typescript
- // Build options
- // build: {
- //   minify: true,
- //   sourceMap: false,
- // },
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/errors.ts src/services/build.ts src/github-action.ts src/cli/commands/init.ts
-git commit -m "docs: update JSDoc and templates for ncc→rsbuild migration
-
-Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>"
-```
-
----
-
-## Task 5: Verify everything works end-to-end
-
-- [ ] **Step 1: Run linting**
-
-```bash
-pnpm run lint:fix
-```
-
-Expected: Clean or auto-fixed.
-
-- [ ] **Step 2: Run typecheck**
-
-```bash
-pnpm run typecheck
-```
-
-Expected: No errors.
-
-- [ ] **Step 3: Run all tests**
-
-```bash
-pnpm run test
-```
-
-Expected: All pass. If build integration tests exist that invoke the actual
-bundler, they should now exercise rsbuild instead of ncc.
-
-- [ ] **Step 4: Run build**
-
-```bash
-pnpm run build
-```
-
-Expected: Package builds successfully (this builds the github-action-builder
-package itself via rslib, not the action bundling).
-
-- [ ] **Step 5: Fix any issues found**
-
-Address any failures from the above steps. Common issues:
-
-- Rsbuild config type mismatches (check `@rsbuild/core` types)
-- Missing rsbuild peer deps
-- Source map config format differences
-
-- [ ] **Step 6: Final commit if fixes were needed**
-
-```bash
-git add -A
-git commit -m "fix: address issues from end-to-end verification
-
-Signed-off-by: C. Spencer Beggs <spencer@savvyweb.systems>"
-```
diff --git a/docs/superpowers/specs/2026-03-19-replace-ncc-with-rsbuild-design.md b/docs/superpowers/specs/2026-03-19-replace-ncc-with-rsbuild-design.md
deleted file mode 100644
index 551bed7..0000000
--- a/docs/superpowers/specs/2026-03-19-replace-ncc-with-rsbuild-design.md
+++ /dev/null
@@ -1,225 +0,0 @@
-# Replace @vercel/ncc with Rsbuild for Action Bundling
-
-**Date:** 2026-03-19
-**Issue:** [#43](https://github.com/savvy-web/github-action-builder/issues/43)
-**Branch:** `feat/use-rsbuild`
-**Status:** Design approved
-
-## Problem
-
-`@vercel/ncc` (webpack 4-based) generates `eval("require")` in ESM output, which
-Node 24 rejects with `ERR_AMBIGUOUS_MODULE_SYNTAX` when combined with top-level
-`await`. This blocks all actions using `node24` with transitive CJS dependencies
-(virtually all `@actions/*` packages via `undici`/`ws`).
-
-ncc is effectively unmaintained and its webpack 4 runtime cannot properly bundle
-CJS modules into ESM output.
-
-## Solution
-
-Replace `@vercel/ncc` with `@rsbuild/core` for programmatic bundling. Rsbuild
-sits at the right abstraction level: clean JS API for bundling without RSLib's
-library-publishing opinions (dts, dual format) or raw Rspack's verbosity.
-
-### Why Rsbuild over alternatives
-
-- **RSLib** is designed for library publishing (dual CJS/ESM, dts generation,
-  package.json transforms). We're bundling an app for deployment, not publishing
-  a package. Square peg, round hole.
-- **Rspack directly** is verbose webpack-style config. We'd reimplement what
-  Rsbuild already provides. Overkill for "bundle TS into single JS file."
-- **Rsbuild** gives us `createRsbuild()` + `.build()` with clean defaults for
-  Node targets, proper CJS/ESM interop, and no unnecessary abstractions.
-
-## Design
-
-### 1. Config schema changes
-
-**Remove from `BuildOptionsSchema`:**
-
-- `target` -- hardcode `es2024` internally. Node 24 (V8 12.x) fully supports
-  ES2024, and the action.yml schema already enforces `using: node24`.
-- `quiet` -- was ncc-specific. CLI `--quiet` flag (which controls console output)
-  is unrelated and stays.
-
-**Remove `EsTarget` schema entirely.** No consumer needs to pick a target.
-
-**Keep unchanged:**
-
-- `minify` (boolean, default `true`)
-- `sourceMap` (boolean, default `false`)
-- `externals` (string[], default `[]`) -- user-specified extras only
-
-**Externals behavior:** `node:*` builtins are always externalized automatically.
-User-provided `externals` are additive. `@actions/*` and all other npm packages
-are bundled (no `node_modules` at runtime in GitHub Actions).
-
-**Impact:** Breaking change to `BuildOptions` type. Consumers who set `target` or
-`quiet` in `action.config.ts` will get a type error. This is intentional
-simplification.
-
-### 2. BuildServiceLive implementation
-
-**File:** `src/services/build-live.ts`
-
-**Remove entirely:**
-
-- `createRequire` / ncc import hack (CJS interop no longer needed)
-- All ncc types (`NccOptions`, `NccAsset`, `NccResult`, `NccFunction`)
-- `bundle()` wrapper function
-- Asset/chunk writing loop (rsbuild with code splitting disabled produces no
-  chunks)
-
-**Replace `bundleEntry()` with rsbuild:**
-
-```typescript
-import { createRsbuild } from "@rsbuild/core";
-
-function bundleEntry(entry, config, cwd) {
-  return Effect.gen(function* () {
-    const startTime = Date.now();
-    const outputDir = resolve(cwd, "dist");
-    const outputFilename = `${entry.type}.js`;
-
-    const rsbuild = await createRsbuild({
-      rsbuildConfig: {
-        source: { entry: { [entry.type]: entry.path } },
-        output: {
-          target: "node",
-          module: true,  // Required: emit ESM, not CJS (experimental flag)
-          distPath: { root: outputDir },
-          filename: { js: "[name].js" },
-          externals: [/^node:/, ...config.build.externals],
-          minify: config.build.minify,
-          sourceMap: config.build.sourceMap
-            ? { js: "source-map" }
-            : false,
-        },
-        performance: {
-          chunkSplit: { strategy: "all-in-one" },
-        },
-      },
-    });
-
-    const buildResult = yield* Effect.tryPromise({
-      try: () => rsbuild.build(),
-      catch: (error) => new BundleFailed({ entry: entry.path, cause: error }),
-    });
-
-    // Release rsbuild resources (file watchers, worker threads)
-    yield* Effect.promise(() => buildResult.close());
-
-    // Read output file size (rsbuild writes to disk directly)
-    const outputPath = resolve(outputDir, `${entry.type}.js`);
-    const size = statSync(outputPath).size;
-    const duration = Date.now() - startTime;
-
-    return {
-      success: true,
-      stats: { entry: entry.type, size, duration, outputPath: entry.output },
-    };
-  });
-}
-```
-
-**Key difference from ncc:** ncc returned code as a string and we wrote it to
-disk. Rsbuild writes to disk directly. `bundleEntry()` reads the output file to
-get size stats rather than measuring a string.
-
-**Note on `output.module`:** This flag is marked experimental in rsbuild. It is
-required to emit ESM instead of CJS. Without it, `output.target: "node"` defaults
-to CJS, which would defeat the purpose of the migration. The `node:*` regex in
-externals is a defensive safety net — rsbuild auto-externalizes Node builtins
-when `target: "node"`, but the explicit regex ensures the `node:` protocol prefix
-form is covered.
-
-**What stays unchanged:**
-
-- `cleanDirectory()`, `writeFile()`, `formatBytes()`, `formatBuildResult()`
-- `getBundleSize()` is removed -- replaced by `statSync(outputPath).size` since
-  rsbuild writes to disk directly (no in-memory string to measure)
-- `build()` orchestration (sequential entry bundling, `dist/package.json` write,
-  result collection)
-- All Effect patterns, error types, Layer composition
-- Explicit `dist/package.json` with `{ "type": "module" }` (we write this
-  ourselves, not left to rsbuild)
-
-### 3. BuildService interface
-
-**File:** `src/services/build.ts`
-
-**No changes.** The interface, schemas (`BuildResult`, `BundleResult`,
-`BundleStats`, `BuildRunnerOptions`), and `Context.Tag` are untouched. This is
-purely an implementation swap behind a stable interface.
-
-### 4. CLI and template changes
-
-**CLI commands** (`src/cli/commands/`):
-
-- `--quiet` flag on `build` and `validate` -- stays as-is (controls console
-  output, not bundler)
-- No `--target` CLI flag exists, nothing to remove
-
-**Init command template** (`src/cli/commands/init.ts`):
-
-- Remove `target: "es2022"` from the generated `action.config.ts` example
-
-**GitHubAction class** (`src/github-action.ts`):
-
-- Update docstring examples that show `target: "es2022"` in config
-
-**Docstring updates across codebase:**
-
-- `defineConfig()` in `config.ts` -- remove `target: "es2022"` from `@example`
-- `BundleFailed` in `errors.ts` -- update JSDoc from "ncc" to "rsbuild"
-- `BuildService` in `build.ts` -- update JSDoc from "vercel/ncc" to "rsbuild"
-
-### 5. Dependency changes
-
-**Remove:**
-
-- `@vercel/ncc` (`^0.38.4`)
-
-**Add:**
-
-- `@rsbuild/core` (programmatic bundling API; brings Rspack as transitive dep)
-
-### 6. Error handling
-
-**No changes to error types.** Existing errors in `src/errors.ts` all still
-apply:
-
-- `BundleFailed` -- wraps rsbuild failures instead of ncc (same shape)
-- `WriteError` -- still used for `dist/package.json`
-- `CleanError` -- unchanged
-
-### 7. Test updates
-
-- `config.test.ts` -- remove assertions for `target` and `quiet` defaults
-- `index.test.ts` -- remove assertions referencing `target`
-- Build integration tests may need updating for rsbuild output format
-  differences (if any)
-
-## Output guarantees
-
-The bundled output for consumer actions must satisfy:
-
-1. **Single file per entry point** (`dist/main.js`, `dist/pre.js`, `dist/post.js`)
-2. **All npm dependencies inlined** (no `node_modules` at runtime)
-3. **Node builtins external** (`node:fs`, `node:path`, etc.)
-4. **ESM format** with `dist/package.json` containing `{ "type": "module" }`
-5. **No `eval("require")`** or CJS/ESM mixing hacks
-6. **Source maps optional** (written by rsbuild when enabled)
-
-## What does NOT change
-
-- `defineConfig()` function signature (consumers just lose two options)
-- `GitHubAction` class public API
-- CLI commands and flags
-- Service interfaces (`BuildService`, `ConfigService`, `ValidationService`)
-- Layer composition (`AppLayer`, `BuildLayer`, etc.)
-- Error types and handling patterns
-- Entry point detection (`src/main.ts`, `src/pre.ts`, `src/post.ts`)
-- Output directory structure (`dist/`)
-- Validation pipeline (action.yml schema, entry file checks)
-- `PersistLocalService` behavior
diff --git a/src/schemas/config.test.ts b/src/schemas/config.test.ts
index 1954b95..f1a92aa 100644
--- a/src/schemas/config.test.ts
+++ b/src/schemas/config.test.ts
@@ -70,6 +70,18 @@ describe("BuildOptions Schema", () => {
 		});
 		expect(decoded.minify).toBe(false);
 	});
+
+	it("defaults ignore to an empty array", () => {
+		const options = Schema.decodeUnknownSync(BuildOptionsSchema)({});
+		expect(options.ignore).toEqual([]);
+	});
+
+	it("accepts an ignore list", () => {
+		const options = Schema.decodeUnknownSync(BuildOptionsSchema)({
+			ignore: ["libxmljs2"],
+		});
+		expect(options.ignore).toEqual(["libxmljs2"]);
+	});
 });
 
 describe("ValidationOptions Schema", () => {
@@ -138,6 +150,13 @@ describe("ConfigInput Schema", () => {
 		expect(decoded.entries?.pre).toBe("pre.ts");
 		expect(decoded.build?.minify).toBe(false);
 	});
+
+	it("accepts build.ignore", () => {
+		const input = Schema.decodeUnknownSync(ConfigInputSchema)({
+			build: { ignore: ["libxmljs2"] },
+		});
+		expect(input.build?.ignore).toEqual(["libxmljs2"]);
+	});
 });
 
 describe("Config Schema", () => {
diff --git a/src/schemas/config.ts b/src/schemas/config.ts
index 27aad63..21c43ca 100644
--- a/src/schemas/config.ts
+++ b/src/schemas/config.ts
@@ -60,6 +60,8 @@ export const BuildOptionsSchema = Schema.Struct({
 	sourceMap: Schema.optionalWith(Schema.Boolean, { default: () => false }),
 	/** Packages to exclude from the bundle (in addition to node: builtins). Defaults to []. */
 	externals: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+	/** Packages to exclude from the bundle and replace with a stub that throws if loaded at runtime. Use for optional transitive dependencies the action never exercises (e.g. native modules). Defaults to []. */
+	ignore: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
 });
 
 /**
@@ -153,6 +155,7 @@ export const ConfigInputSchema = Schema.Struct({
 			minify: Schema.optional(Schema.Boolean),
 			sourceMap: Schema.optional(Schema.Boolean),
 			externals: Schema.optional(Schema.Array(Schema.String)),
+			ignore: Schema.optional(Schema.Array(Schema.String)),
 		}),
 	),
 	validation: Schema.optional(
@@ -253,6 +256,7 @@ export type Config = typeof ConfigSchema.Type;
  *     minify: true,
  *     sourceMap: true,
  *     externals: ["@aws-sdk/client-s3"],
+ *     ignore: ["libxmljs2"],
  *   },
  *   validation: {
  *     requireActionYml: true,
diff --git a/src/services/build-live.ts b/src/services/build-live.ts
index 8822064..b2adcba 100644
--- a/src/services/build-live.ts
+++ b/src/services/build-live.ts
@@ -3,8 +3,9 @@
  * BuildService Layer implementation.
  *
  */
-import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { createRsbuild } from "@rsbuild/core";
 import { Effect, Layer } from "effect";
 
@@ -15,6 +16,12 @@ import { BuildService } from "./build.js";
 import type { DetectedEntry } from "./config.js";
 import { ConfigService } from "./config.js";
 
+/**
+ * Source of the stub module that replaces packages listed in `build.ignore`.
+ * It is bundled in place of the real module and throws if ever loaded.
+ */
+const IGNORE_STUB_SOURCE = `throw new Error("A module excluded via the build 'ignore' option was loaded at runtime.");\n`;
+
 /**
  * Format bytes as a human-readable string.
  */
@@ -116,30 +123,69 @@ function bundleEntry(
 		const startTime = Date.now();
 		const outputDir = resolve(cwd, "dist");
 
+		// Modules listed in `build.ignore` are aliased to a throwing stub so
+		// they are neither bundled nor resolved against node_modules. The stub
+		// lives in a private per-build temp directory created with mkdtemp, so
+		// a predictable shared path cannot be pre-created or symlinked by
+		// another process. See
+		// docs/superpowers/specs/2026-05-15-build-ignore-option-design.md.
+		const externalsSet = new Set(config.build.externals);
+		const ignoreSet = new Set(config.build.ignore);
+		const ignoreAlias: Record<string, string> = {};
+		let stubDir: string | undefined;
+		if (config.build.ignore.length > 0) {
+			stubDir = yield* Effect.try({
+				try: () => mkdtempSync(join(tmpdir(), "github-action-builder-")),
+				catch: (error) => new WriteError({ path: tmpdir(), cause: error }),
+			});
+			const stubPath = resolve(stubDir, "ignore-stub.mjs");
+			yield* writeFile(stubPath, IGNORE_STUB_SOURCE);
+			for (const moduleName of config.build.ignore) {
+				ignoreAlias[`${moduleName}$`] = stubPath;
+			}
+		}
+
 		// createRsbuild returns a Promise<RsbuildInstance>
 		const rsbuild = yield* Effect.tryPromise({
 			try: () =>
 				createRsbuild({
 					rsbuildConfig: {
 						source: { entry: { [entry.type]: entry.path } },
+						resolve: { alias: ignoreAlias },
 						output: {
 							target: "node",
 							module: true,
 							distPath: { root: outputDir },
 							filename: { js: "[name].js" },
-							externals: [
-								// Externalize node: builtins with CommonJS require() semantics.
-								// Output is ESM (output.module), so a RegExp external would
-								// resolve with the default "module" type, making
-								// require("node:*") inside bundled CJS deps return an ESM
-								// namespace object. That breaks the TypeScript __importDefault
-								// interop helper and throws "instanceof is not callable" at
-								// runtime. "node-commonjs" preserves real require() semantics.
-								// See issue #79.
-								(data: { request?: string }): string | false =>
-									data.request?.startsWith("node:") ? `node-commonjs ${data.request}` : false,
-								...config.build.externals,
-							],
+							// A single function makes the whole externalization decision so
+							// it never depends on rspack's array fall-through. Leading the
+							// array with a function caused rspack to stop consulting trailing
+							// string entries, so user-configured externals were bundled and
+							// hard-failed to resolve instead of being externalized (#81).
+							externals: (data: { request?: string }): string | false => {
+								const request = data.request;
+								if (!request) {
+									return false;
+								}
+								// node: builtins are externalized with CommonJS require()
+								// semantics. Output is ESM (output.module), so the default
+								// "module" type makes require("node:*") inside bundled CJS deps
+								// return an ESM namespace object. That breaks the TypeScript
+								// __importDefault interop helper and throws "instanceof is not
+								// callable" at runtime. "node-commonjs" preserves real
+								// require() semantics. See issue #79.
+								if (request.startsWith("node:")) {
+									return `node-commonjs ${request}`;
+								}
+								// User-configured externals: not bundled, left as runtime
+								// imports with the default external type.
+								// `ignore` takes precedence over `externals`: a module in
+								// both lists is stubbed via resolve.alias, not externalized.
+								if (externalsSet.has(request) && !ignoreSet.has(request)) {
+									return request;
+								}
+								return false;
+							},
 							cleanDistPath: false,
 							minify: config.build.minify,
 							sourceMap: config.build.sourceMap ? { js: "source-map" as const } : false,
@@ -175,6 +221,12 @@ function bundleEntry(
 				}),
 		});
 
+		// Remove the private stub directory now the bundle has been written.
+		if (stubDir !== undefined) {
+			const dir = stubDir;
+			yield* Effect.ignore(Effect.try(() => rmSync(dir, { recursive: true, force: true })));
+		}
+
 		const outputPath = resolve(outputDir, `${entry.type}.js`);
 		const size = yield* Effect.try({
 			try: () => statSync(outputPath).size,