docs(bootstrap): correct the self-registration invariant and the isolated-context example

.claude/CLAUDE.md

@@ -298,7 +298,7 @@ Pre-built tasks: `InputTask`, `OutputTask`, `LambdaTask`, `DelayTask`, `FetchUrl
 
 ### `@workglow/bootstrap` — default registration
 
-Nothing self-registers at import time, so a runtime has to install the defaults before any task runs. This package is that seam, and **the implementation lives here** — `packages/workglow/src/bootstrap.ts` is now a pure `export * from "@workglow/bootstrap"` re-export shim. Add a new default registration in `packages/bootstrap/src/bootstrap/registerAllDefaults.ts`; editing the shim does nothing.
+Each registrar self-registers on the **global** registry when its module happens to be imported — `registerModelDefaults()`, `registerTabularStorageDefaults()` and the twelve others run at module scope, and default their `registry` parameter to the global one. What is populated therefore depends on which modules your import graph has pulled in, which is import-order dependent and easy to mis-diagnose. `bootstrapWorkglow()` is the guarantee: it installs the full set in dependency order, idempotently. An isolated registry gets **nothing** until `registerAllDefaults(registry)` (or `createOrchestrationContext()`) is called explicitly. This package is that seam, and **the implementation lives here** — `packages/workglow/src/bootstrap.ts` is now a pure `export * from "@workglow/bootstrap"` re-export shim. Add a new default registration in `packages/bootstrap/src/bootstrap/registerAllDefaults.ts`; editing the shim does nothing.
 
 - `bootstrapWorkglow(opts?)` — installs defaults onto the global registry, idempotent. The normal application entry point.
 - `createOrchestrationContext(opts?)` — a fresh, disposable registry backed by its own container (tests, multi-tenant servers, embedded use).

packages/bootstrap/README.md

@@ -2,11 +2,19 @@
 
 Runtime bootstrap for Workglow: registers every built-in default onto a service registry.
 
-Workglow does not self-register defaults at import time. Something has to install
-the logger, telemetry, worker-manager, credential, model, provider, knowledge-base,
-MCP, storage, task, and transform factories before any task runs — this package is
-that something, sitting below both the `workglow` meta-package and the test harness
-so neither has to own its own copy.
+Each registrar self-registers on the **global** registry when its module happens to
+be imported — `registerModelDefaults()`, `registerTabularStorageDefaults()` and the
+twelve others run at module scope, and default their `registry` parameter to the
+global one. What is populated therefore depends on which modules your import graph
+has pulled in, which is import-order dependent and easy to mis-diagnose.
+`bootstrapWorkglow()` is the guarantee: it installs the full set — logger,
+telemetry, worker-manager, credential, model, provider, knowledge-base, MCP,
+storage, task, and transform factories — in dependency order, idempotently. An
+isolated registry gets **nothing** until `registerAllDefaults(registry)` (or
+`createOrchestrationContext()`) is called explicitly.
+
+This package is that seam, sitting below both the `workglow` meta-package and the
+test harness so neither has to own its own copy.
 
 ## Installation
 
@@ -51,12 +59,17 @@ import { createOrchestrationContext } from "@workglow/bootstrap";
 
 const ctx = createOrchestrationContext();
 try {
-  await task.run({ context: ctx });
+  await task.run({}, { registry: ctx.registry });
 } finally {
   await ctx.dispose();
 }
 ```
 
+The registry travels in the **run config** — `run()`'s second argument. The first
+argument is input overrides, so passing a context there silently becomes an input
+named `context`, the run uses the global registry, and `ctx.dispose()` tears down a
+registry nothing ever touched.
+
 ### Registering onto a registry you already have
 
 ```typescript

packages/bootstrap/src/bootstrap/bootstrapWorkglow.ts

@@ -72,7 +72,10 @@ export function bootstrapWorkglow(opts: BootstrapOptions = {}): WorkglowContext
  * ```ts
  * const ctx = createOrchestrationContext({ logger: new MyLogger() });
  * try {
- *   await task.run({ ..., context: ctx });
+ *   // The registry travels in the run config — `run()`'s FIRST argument is
+ *   // input overrides, so a context passed there is just an input named
+ *   // `context` and the run still uses the global registry.
+ *   await task.run({}, { registry: ctx.registry });
  * } finally {
  *   await ctx.dispose();
  * }

packages/bootstrap/src/bootstrap/registerAllDefaults.ts

@@ -9,13 +9,13 @@ import { registerKnowledgeBaseDefaults } from "@workglow/knowledge-base";
 import { registerMcpServerDefaults } from "@workglow/mcp/util";
 import { registerTabularStorageDefaults } from "@workglow/storage";
 import { registerTaskDefaults, registerTransformDefaults } from "@workglow/task-graph";
+import type { ServiceRegistry } from "@workglow/util";
 import {
   registerCredentialDefaults,
   registerInputCompactorDefaults,
   registerInputResolverDefaults,
   registerLoggerDefaults,
   registerTelemetryDefaults,
-  ServiceRegistry,
 } from "@workglow/util";
 import { registerImageDefaults } from "@workglow/util/media";
 import { registerWorkerManagerDefaults } from "@workglow/util/worker";

packages/test/package.json

@@ -39,6 +39,7 @@
     "@workglow/ai": "workspace:*",
     "@workglow/anthropic": "workspace:*",
     "@workglow/aws": "workspace:*",
+    "@workglow/bootstrap": "workspace:*",
     "@workglow/browser-control": "workspace:*",
     "@workglow/bun-webview": "workspace:*",
     "@workglow/cactus": "workspace:*",

packages/test/src/test/util/BootstrapReadme.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Executable transcription of the "Isolated context" example in
+ * `packages/bootstrap/README.md` (and the matching `createOrchestrationContext`
+ * JSDoc example).
+ *
+ * The README used to show `await task.run({ context: ctx })`. `Task.run` takes
+ * input overrides first and a run config second, and neither `IRunConfig` nor
+ * `TaskGraphRunConfig` has a `context` key — so with a loosely typed `Input`
+ * that object is an input override named `context`, the run keeps the global
+ * registry, and `ctx.dispose()` tears down a registry the task never touched.
+ * Both halves are pinned below so the snippet cannot silently rot back.
+ */
+
+import { createOrchestrationContext } from "@workglow/bootstrap";
+import type { IExecuteContext, TaskInput, TaskOutput } from "@workglow/task-graph";
+import { Task } from "@workglow/task-graph";
+import type { ServiceRegistry } from "@workglow/util";
+import { globalServiceRegistry } from "@workglow/util";
+import type { DataPortSchema } from "@workglow/util/schema";
+import { describe, expect, it } from "vitest";
+
+interface RegistryProbeOutput extends TaskOutput {
+  isGlobal: boolean;
+}
+
+/** Reports whether the run resolved against the process-wide registry. */
+class RegistryProbeTask extends Task<TaskInput, RegistryProbeOutput> {
+  public static override readonly type = "RegistryProbeTask";
+  public static override readonly category = "Test";
+  public static override readonly title = "Registry probe";
+  public static override readonly description = "Reports which service registry the run used.";
+  public static override readonly cacheable = false;
+
+  public static override inputSchema(): DataPortSchema {
+    return {
+      type: "object",
+      properties: {},
+      additionalProperties: true,
+    } as const satisfies DataPortSchema;
+  }
+
+  public static override outputSchema(): DataPortSchema {
+    return {
+      type: "object",
+      properties: { isGlobal: { type: "boolean" } },
+      additionalProperties: false,
+    } as const satisfies DataPortSchema;
+  }
+
+  public seenRegistry: ServiceRegistry | undefined;
+
+  public override async execute(
+    _input: TaskInput,
+    context: IExecuteContext
+  ): Promise<RegistryProbeOutput> {
+    this.seenRegistry = context.registry;
+    return { isGlobal: context.registry === globalServiceRegistry };
+  }
+}
+
+describe("the @workglow/bootstrap README isolated-context example", () => {
+  it("routes the run to the isolated registry when the context is passed in the run config", async () => {
+    const ctx = createOrchestrationContext();
+    const task = new RegistryProbeTask();
+    try {
+      const output = await task.run({}, { registry: ctx.registry });
+
+      expect(output.isGlobal).toBe(false);
+      expect(task.seenRegistry).toBe(ctx.registry);
+    } finally {
+      await ctx.dispose();
+    }
+  });
+
+  it("keeps the global registry when a context is passed as an input override instead", async () => {
+    const ctx = createOrchestrationContext();
+    const task = new RegistryProbeTask();
+    try {
+      // The shape the README used to document. It type-checks only because this
+      // task's input schema is open; the run silently ignores it.
+      const output = await task.run({ context: ctx });
+
+      expect(output.isGlobal).toBe(true);
+      expect(task.seenRegistry).not.toBe(ctx.registry);
+    } finally {
+      await ctx.dispose();
+    }
+  });
+});

packages/test/tsconfig.json

@@ -21,6 +21,7 @@
     { "path": "../indexeddb" },
     { "path": "../mcp" },
     { "path": "../browser-control" },
+    { "path": "../bootstrap" },
     { "path": "../../providers/anthropic" },
     { "path": "../../providers/bun-webview" },
     { "path": "../../providers/deepseek" },