opencode-effect-enforcer 0.2.8 → 0.3.0

package/skills/effect-command-executor/SKILL.md

@@ -5,13 +5,16 @@ description: Spawn and manage child processes using Effect's ChildProcess module
 
 # Child Process Execution with Effect v4
 
+Targets **Effect 4.0.0**, checked against the `effect@4.0.0` source tag. Keep platform packages on the same version. The process API is marked `@stability unstable`, so check contracts again before a minor-version upgrade.
+
 ## Overview
 
-Node process-group cleanup waits for the leader and descendants. Without
+On POSIX, Node process-group cleanup waits for the leader and descendants. Without
 `forceKillAfter`, cleanup waits up to one second without escalating. With it,
 the group receives SIGKILL at the deadline, then a final bounded wait. Native
 timers drive escalation even under TestClock. `exitCode` / `isRunning` describe
 the leader, not all descendants; do not use virtual time alone to prove OS cleanup.
+On Windows, Node uses `taskkill` for tree termination and waits for the leader.
 
 The `ChildProcess` module provides type-safe, composable process execution with automatic resource cleanup via `Scope`. Commands are AST values — built first with `make` and `pipeTo`, then executed via the `ChildProcessSpawner` service.
 
@@ -23,12 +26,12 @@ The `ChildProcess` module provides type-safe, composable process execution with
 - Streaming output from long-running processes
 - Managing process lifecycles with scoped cleanup
 
-**Note:** This skill covers child process execution, NOT `@effect/cli` for building CLI applications.
+**Note:** This skill covers child process execution; use `effect/cli` for building CLI applications.
 
 ## Import Pattern
 
 ```typescript
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 ```
 
 Platform layer (Node.js):
@@ -41,8 +44,9 @@ import { NodeServices } from '@effect/platform-node';
 
 ### Template Literal Form
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Simple command — parsed by whitespace
 const cmd = ChildProcess.make`echo hello world`;
@@ -58,8 +62,9 @@ const cmd3 = ChildProcess.make`oxfmt ${files}`;
 
 ### Options + Template Literal Form
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Options object returns a tagged template function
 const cmd = ChildProcess.make({ cwd: '/tmp' })`ls -la`;
@@ -73,8 +78,9 @@ const cmd2 = ChildProcess.make({
 
 ### Array Form
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Explicit command + args array
 const cmd = ChildProcess.make('git', ['status'], {
@@ -99,8 +105,9 @@ const cmd3 = ChildProcess.make('node', {
 
 ### Command Options
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 const cmd = ChildProcess.make('node', ['script.js'], {
 	// Working directory
@@ -141,8 +148,9 @@ The `fd3`/`fd4` names configure child-process stdio channels. Process handles ex
 
 ### Combinators
 
+<!-- typecheck -->
 ```typescript
-import { ChildProcess } from 'effect/unstable/process';
+import { ChildProcess } from 'effect/process';
 
 // Set cwd (applies to all commands in a pipeline)
 const cmd = ChildProcess.make`ls -la`.pipe(ChildProcess.setCwd('/tmp'));
@@ -165,7 +173,7 @@ Commands are `Effect` values: `yield*` on a command evaluates through its `Effec
 
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -175,9 +183,10 @@ const program = Effect.gen(function* () {
 
 ### Capture as String
 
+<!-- typecheck -->
 ```typescript
 import { Effect, String } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -190,39 +199,45 @@ const program = Effect.gen(function* () {
 
 ### Capture as Lines
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Arr from 'effect/Array';
+import * as Str from 'effect/String';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const files = yield* spawner.lines(
 		ChildProcess.make('git', ['diff', '--name-only', 'main...HEAD'])
 	);
-	const tsFiles = files.filter((f) => f.endsWith('.ts'));
+	const tsFiles = Arr.filter(files, Str.endsWith('.ts'));
 });
 ```
 
 ### Progressive Output with Side Effects
 
+<!-- typecheck -->
 ```typescript
 import { Effect, Stream } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-	let output = '';
 	const handle = yield* spawner.spawn(
 		ChildProcess.make('bun', ['test'], {
 			extendEnv: true,
 			stdin: 'ignore'
 		})
 	);
-	yield* Stream.runForEach(Stream.decodeText(handle.all), (chunk) =>
-		Effect.sync(() => {
-			output += chunk;
-		})
-	).pipe(Effect.forkScoped);
+	// Drain to EOF before leaving the scope, propagating read/progress failures.
+	const output = yield* handle.all.pipe(
+		Stream.decodeText(),
+		Stream.tap((chunk) => Effect.logDebug('Process output').pipe(
+			Effect.annotateLogs({ characters: chunk.length })
+		)),
+		Stream.mkString
+	);
 	const exitCode = yield* handle.exitCode;
 	return { output, exitCode };
 }).pipe(Effect.scoped);
@@ -230,29 +245,41 @@ const program = Effect.gen(function* () {
 
 Use this pattern when you need per-chunk side effects (progress reporting, streaming to UI) during command execution. `spawner.string`/`spawner.lines` cannot provide per-chunk callbacks.
 
+Waiting for `handle.exitCode` alone does not drain output. If you fork a reader, join it before closing the scope and returning captured output. `Stream.mkString` buffers all text; for unbounded output, use `Stream.runForEach` without retaining it. Treat process output as potentially sensitive when choosing a progress callback.
+
 ### Get Exit Code
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Schema from 'effect/Schema';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
+
+class CommandFailed extends Schema.TaggedError<CommandFailed>()('CommandFailed', {
+	exitCode: Schema.Number
+}) {}
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const exitCode = yield* spawner.exitCode(
-		ChildProcess.make('test', ['-f', 'package.json'])
+		ChildProcess.make('test', ['-f', 'package.json'], {
+			stdin: 'ignore', stdout: 'ignore', stderr: 'ignore'
+		})
 	);
 	// exitCode: ExitCode (branded number)
 	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-		yield* Effect.fail(new Error('file not found'));
+		return yield* Effect.fail(new CommandFailed({ exitCode }));
 	}
 });
 ```
 
+`string`, `lines`, and stream helpers collect output; they do **not** reject a nonzero exit code. Use a scoped handle when success requires both captured output and a checked status. When using `exitCode` alone, inherit or ignore stdout/stderr so an unread pipe cannot fill and stall a noisy process. Output helpers default to stdout; pass `{ includeStderr: true }` to consume combined output, or configure stderr as `inherit`/`ignore` when only stdout is needed.
+
 ### Stream Output (Long-Running Processes)
 
 ```typescript
 import { Console, Effect, Stream } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -273,9 +300,15 @@ const program = Effect.gen(function* () {
 
 Use `spawner.spawn` when you need the process handle for interactive control, streaming output while running, or checking exit codes.
 
+<!-- typecheck -->
 ```typescript
 import { Console, Effect, Stream } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Schema from 'effect/Schema';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
+
+class LintFailed extends Schema.TaggedError<LintFailed>()('LintFailed', {
+	exitCode: Schema.Number
+}) {}
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -298,7 +331,7 @@ const program = Effect.gen(function* () {
 	// Wait for exit
 	const exitCode = yield* handle.exitCode;
 	if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-		yield* Effect.fail(new Error(`lint failed: exit ${exitCode}`));
+		return yield* Effect.fail(new LintFailed({ exitCode }));
 	}
 }).pipe(Effect.scoped); // <-- spawn requires Scope
 ```
@@ -310,7 +343,7 @@ const program = Effect.gen(function* () {
 | `pid`             | `ProcessId`                                    | Process identifier (branded number)                                        |
 | `exitCode`        | `Effect<ExitCode, PlatformError>`              | Waits for exit, returns exit code                                          |
 | `isRunning`       | `Effect<boolean, PlatformError>`               | Check if still running                                                     |
-| `kill(options?)`  | `Effect<void, PlatformError>`                  | Kill with signal; pass `{ forceKillAfter: '3 seconds' }` to ensure cleanup |
+| `kill(options?)`  | `Effect<void, PlatformError>`                  | Kill with signal; `forceKillAfter` bounds graceful waiting before escalation |
 | `stdin`           | `Sink<void, Uint8Array, never, PlatformError>` | Write to process stdin                                                     |
 | `stdout`          | `Stream<Uint8Array, PlatformError>`            | Read process stdout                                                        |
 | `stderr`          | `Stream<Uint8Array, PlatformError>`            | Read process stderr                                                        |
@@ -320,9 +353,10 @@ const program = Effect.gen(function* () {
 
 ## Piping Commands
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -371,12 +405,18 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
 ```
 
-Or provide just the spawner:
+Or compose the spawner with its FileSystem and Path dependencies:
 
 ```typescript
-import { NodeChildProcessSpawner } from '@effect/platform-node';
+import { NodeChildProcessSpawner, NodeFileSystem, NodePath } from '@effect/platform-node';
+import { Effect, Layer } from 'effect';
+import { ChildProcessSpawner } from 'effect/process';
 
-const program = myEffect.pipe(Effect.provide(NodeChildProcessSpawner.layer));
+declare const myEffect: Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner>;
+const SpawnerLayer = NodeChildProcessSpawner.layer.pipe(
+	Layer.provide(Layer.mergeAll(NodeFileSystem.layer, NodePath.layer))
+);
+const program = myEffect.pipe(Effect.provide(SpawnerLayer));
 ```
 
 ## Complete Example: DevTools Service
@@ -392,7 +432,8 @@ import {
 	Stream,
 	String
 } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import * as Arr from 'effect/Array';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 class DevToolsError extends Schema.TaggedError<DevToolsError>()(
 	'DevToolsError',
@@ -442,7 +483,7 @@ class DevTools extends Context.Service<
 					.pipe(
 						Effect.mapError((cause) => new DevToolsError({ cause }))
 					);
-				return files.filter((file) => file.endsWith('.ts'));
+				return Arr.filter(files, String.endsWith('.ts'));
 			});
 
 			const recentCommitSubjects = spawner
@@ -463,7 +504,7 @@ class DevTools extends Context.Service<
 			const runLintFix = Effect.gen(function* () {
 				const handle = yield* spawner
 					.spawn(
-						ChildProcess.make('bun', ['lint'], {
+						ChildProcess.make('bun', ['lint', '--fix'], {
 							env: { FORCE_COLOR: '1' },
 							extendEnv: true,
 							stdin: 'ignore'
@@ -484,11 +525,9 @@ class DevTools extends Context.Service<
 					Effect.mapError((cause) => new DevToolsError({ cause }))
 				);
 				if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-					return yield* new DevToolsError({
-						cause: new Error(
-							`bun lint failed with exit code ${exitCode}`
-						)
-					});
+					return yield* Effect.fail(new DevToolsError({
+						cause: { command: 'bun lint --fix', exitCode }
+					}));
 				}
 			}).pipe(Effect.scoped);
 
@@ -499,7 +538,9 @@ class DevTools extends Context.Service<
 				runLintFix
 			});
 		})
-	).pipe(Layer.provide(NodeServices.layer));
+	);
+
+	static readonly defaultLayer = DevTools.layer.pipe(Layer.provide(NodeServices.layer));
 }
 ```
 
@@ -516,14 +557,14 @@ const program = Effect.gen(function* () {
 }).pipe(Effect.scoped);
 ```
 
-### DON'T: Use `spawner.spawn` without scoping
+### DON'T: Run a scoped program without providing its Scope
 
 ```typescript
-// Process handle leaks — no scope to manage cleanup
+// This definition is valid and retains Scope in its requirements.
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
 	const handle = yield* spawner.spawn(ChildProcess.make`my-server`);
-	// ❌ no Effect.scoped — process may leak
+	// The caller must own/provide Scope before running this program.
 });
 ```
 
@@ -571,22 +612,15 @@ class MyService extends Context.Service<
 >()('MyService') {}
 ```
 
-### DO: Check `ExitCode` with the branded constructor
+### DO: Check the exit status explicitly
 
 ```typescript
 if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
-	yield* Effect.fail(new Error(`command failed: ${exitCode}`));
+	return yield* Effect.fail(new CommandFailed({ exitCode }));
 }
 ```
 
-### DON'T: Compare exit codes as raw numbers
-
-```typescript
-// ❌ ExitCode is a branded type — direct number comparison may not work as expected
-if (exitCode !== 0) {
-	/* ... */
-}
-```
+`ExitCode` is a branded **number**, not a boxed runtime value. Both `exitCode !== 0` and comparison with `ChildProcessSpawner.ExitCode(0)` work. The constructor is useful when supplying an ExitCode to a typed API; the brand does not change numeric comparison semantics.
 
 ### DO: Use `handle.all` for interleaved stdout+stderr
 
@@ -610,9 +644,10 @@ yield* Stream.merge(handle.stdout, handle.all).pipe(Stream.runCollect);
 
 Child process operations fail with `PlatformError`:
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
-import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
+import { ChildProcess, ChildProcessSpawner } from 'effect/process';
 
 const program = Effect.gen(function* () {
 	const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
@@ -621,7 +656,9 @@ const program = Effect.gen(function* () {
 		.string(ChildProcess.make`non-existent-command`)
 		.pipe(
 			Effect.catchTag('PlatformError', (error) =>
-				Effect.succeed(`fallback: ${error.message}`)
+				error.reason._tag === 'NotFound'
+					? Effect.succeed('Optional command is unavailable')
+					: Effect.fail(error)
 			)
 		);
 });
@@ -637,6 +674,7 @@ Keep process kill, timeout, and output-drain logic inside the process adapter th
 
 Use `Effect.callback` to convert an `AbortSignal` (or any event-driven API) into an Effect. The cleanup Effect removes the listener, and the already-aborted edge case is handled first:
 
+<!-- typecheck -->
 ```typescript
 import { Effect } from 'effect';
 
@@ -651,16 +689,25 @@ const fromAbortSignal = (signal: AbortSignal) =>
 
 ### Abort / Timeout Multiplexing
 
-Combine `Effect.raceAll` with discriminated result types to handle exit, abort, and timeout in a single expression:
+Combine `Effect.raceAll` with discriminated result types to handle successful exit, abort, and timeout in a single expression. `raceAll` waits for the first success, so turn exit observation into an `Exit` value to preserve a failed exit-code read rather than hiding it behind the timeout:
 
+<!-- typecheck -->
 ```typescript
-import { Effect } from 'effect';
-
-const exit =
-	yield*
-	Effect.raceAll([
+import { Duration, Effect } from 'effect';
+import { ChildProcessSpawner } from 'effect/process';
+
+declare const fromAbortSignal: (signal: AbortSignal) => Effect.Effect<void>;
+
+// Call within the scope that owns the handle and its output reader.
+const awaitOutcome = Effect.fn('Process.awaitOutcome')(function* (
+	handle: ChildProcessSpawner.ChildProcessHandle,
+	signal: AbortSignal,
+	timeout: Duration.Input
+) {
+	const exit = yield* Effect.raceAll([
 		handle.exitCode.pipe(
-			Effect.map((code) => ({ kind: 'exit' as const, code }))
+			Effect.exit,
+			Effect.map((result) => ({ kind: 'exit' as const, result }))
 		),
 		fromAbortSignal(signal).pipe(
 			Effect.map(() => ({ kind: 'abort' as const }))
@@ -669,11 +716,15 @@ const exit =
 			Effect.map(() => ({ kind: 'timeout' as const }))
 		)
 	]);
-if (exit.kind !== 'exit') {
-	yield* handle.kill({ forceKillAfter: '3 seconds' });
-}
+	if (exit.kind !== 'exit') {
+		yield* handle.kill({ forceKillAfter: '3 seconds' });
+	}
+	return exit;
+});
 ```
 
+Handle `exit.result` with `Exit.match` when `kind === 'exit'`; it includes observation failures. This race only chooses the control outcome: drain/join any output reader separately within the owning scope before returning captured output.
+
 ## Related Skills
 
 - **effect-platform-abstraction**: FileSystem, Path, and other platform services

package/skills/effect-concurrency-testing/SKILL.md

@@ -16,12 +16,15 @@ This skill provides patterns for testing Effect's concurrency primitives: fibers
 | Simple fiber yield                | `Effect.yieldNow`                                                                     |
 | Wait for subscriber ready         | `Deferred.make()` + `Deferred.await`                                                  |
 | Wait for stream element           | `Latch.make()` + `Stream.tap(() => latch.open)`                                       |
-| Passive subscription registration | explicit readiness signal if possible; otherwise a tiny one-tick yield/sleep fallback |
+| Passive subscription registration | acquire `PubSub.subscribe` before publishing, or expose a readiness signal             |
 | Time-dependent behavior           | `TestClock.adjust`                                                                    |
 | Verify events published           | `PubSub.subscribe` + `PubSub.takeUpTo`                                                |
 | Check fiber status                | `fiber.pollUnsafe()`                                                                  |
 
-For `Stream.fromPubSub` subscription registration, prefer an explicit readiness signal when you control the stream. If the API offers no readiness hook and you only need registration to settle before publishing, a tiny `Effect.yieldNow()` or very short sleep is an acceptable last resort. Avoid broad polling or arbitrary delays.
+For `Stream.fromPubSub` registration, signal readiness after acquiring the actual
+subscription, not merely before starting the stream. A scheduler yield is not a
+general readiness guarantee; a sleep under `it.effect` also needs `TestClock`
+advancement. Prefer a subscription-first test seam to arbitrary delays.
 
 ## Fiber Coordination Patterns
 
@@ -39,7 +42,7 @@ it.effect('fiber polling with yieldNow', () =>
 
 		const fiber = yield* latch.await.pipe(Effect.forkChild);
 
-		yield* Effect.yieldNow();
+		yield* Effect.yieldNow;
 
 		expect(fiber.pollUnsafe()).toBeUndefined();
 
@@ -67,7 +70,7 @@ it.effect('latch coordination', () =>
 			return 'completed';
 		}).pipe(Effect.forkChild);
 
-		yield* Effect.yieldNow();
+		yield* Effect.yieldNow;
 		expect(fiber.pollUnsafe()).toBeUndefined();
 
 		yield* latch.open;
@@ -436,6 +439,23 @@ it.effect('should run finalizers', () =>
 
 ## Interruption Testing
 
+Test cancellation at the resource-owning boundary, using a `Deferred` to prove
+work has started before interrupting it:
+
+- Shared `ScopedCache` lookup: cancel one of two waiters and let the other
+  finish; then cancel the last waiter on another pending lookup and verify its
+  resource finalizer ran and a later `get` reacquires.
+- `race` / `raceFirst` / iterable variants: assert loser cleanup is complete when
+  the race returns, including cancellation while contenders are starting.
+- `Scope.close`: gate a finalizer, interrupt the closing fiber, release the gate,
+  and verify remaining finalizers still run.
+- `ManagedRuntime.dispose`: verify request cleanup can use layer services before
+  those services are released.
+- Queue batches: offer fewer than `takeN` requests, verify the taker remains
+  pending, then `end` or `fail` and assert the short final batch precedes the
+  terminal outcome. For PubSub, test the `end` value with `take`, not `takeUpTo`,
+  including a late subscriber and a full dropping buffer.
+
 ### Testing Fiber Interruption
 
 ```typescript
@@ -518,7 +538,7 @@ Effect.gen(function* () {
 // GOOD - Use yieldNow for simple yielding
 Effect.gen(function* () {
 	const fiber = yield* someEffect.pipe(Effect.forkChild);
-	yield* Effect.yieldNow();
+	yield* Effect.yieldNow;
 	yield* Fiber.join(fiber);
 });
 ```
@@ -538,7 +558,7 @@ while (fiber.pollUnsafe() === undefined) {
 // GOOD - Yield between polls or use Fiber.await
 Effect.gen(function* () {
 	while (fiber.pollUnsafe() === undefined) {
-		yield* Effect.yieldNow();
+		yield* Effect.yieldNow;
 	}
 });
 

package/skills/effect-config/SKILL.md

@@ -89,9 +89,36 @@ const host = Config.String('HOST').pipe(
 );
 ```
 
+The fallback result replaces the original failure. If the fallback is absent,
+an outer `withDefault` or `option` can recover it even when the primary input
+was invalid. If the fallback fails, its error propagates. `Config.fail(error)`
+has type `Config<never>` and does not widen a composed result to `unknown`.
+
+### `Config.flatMap` — Select a Dependent Config
+
+Use `map` for a pure value transformation, `mapEffect` for a transformation that
+may fail with `ConfigError`, and `flatMap` when the parsed value selects another
+`Config`. The selected config uses the same provider and nesting prefix; the
+callback runs only after successful resolution of the first config.
+
+<!-- typecheck -->
+```ts
+import { Config, ConfigProvider } from 'effect';
+
+const host = Config.Literals(['development', 'production'], 'MODE').pipe(
+	Config.flatMap((mode) => Config.NonEmptyString(
+		mode === 'development' ? 'DEV_HOST' : 'PROD_HOST'
+	)),
+	Config.nested('APP')
+);
+const parsed = host.parse(ConfigProvider.fromUnknown({
+	APP: { MODE: 'production', PROD_HOST: 'api.example.com' }
+}));
+```
+
 ### `Config.all` — Combine Multiple Configs
 
-Accepts a record or a tuple:
+Accepts a record, tuple, or iterable of configs:
 
 ```ts
 // As a record
@@ -105,6 +132,28 @@ const appConfig = Config.all({
 const pair = Config.all([Config.String('a'), Config.Int('b')]);
 ```
 
+A group is absent when any child is absent and no child fails, even if other
+children have supplied values. `Config.option(group)` then returns `None`;
+`Config.withDefault(group, fallback)` replaces the **whole group**. Put defaults
+on individual children to retain supplied siblings. Validation and source
+errors still propagate. Use `Config.schema(Schema.Struct(...))` when an existing
+but incomplete object must fail validation rather than default.
+
+<!-- typecheck -->
+```ts
+import { Config, ConfigProvider, Effect } from 'effect';
+
+const group = Config.all({
+	host: Config.String('HOST'),
+	port: Config.Int('PORT')
+}).pipe(Config.withDefault({ host: 'localhost', port: 3000 }));
+
+const result = Effect.runSync(group.parse(
+	ConfigProvider.fromUnknown({ HOST: 'supplied.example.com' })
+));
+// { host: 'localhost', port: 3000 } — the supplied host is replaced too.
+```
+
 ### `Config.nested` — Scope Under a Prefix
 
 Prepends a path segment to every key the inner config reads. With environment variables, nesting uses `_` as separator.
@@ -346,7 +395,9 @@ const defaults = ConfigProvider.fromUnknown({
 const combined = ConfigProvider.orElse(envProvider, defaults);
 ```
 
-At the `Config` level, `Config.orElse` preserves evidence that the primary branch read provider input. Consequently, an outer `Config.withDefault` or `Config.option` does not hide a partially supplied `Config.all` group.
+At the `Config` level, `Config.orElse` handles missing data and all `ConfigError`s;
+its fallback determines whether an outer default or option can recover. Provider
+fallback only chooses a source and does not perform that error recovery.
 
 ### `ConfigProvider.nested` — Prefix All Lookups
 

package/skills/effect-context-witness/SKILL.md

@@ -36,7 +36,7 @@ export const PaymentIntent = Schema.Struct({
 Field **removed from schema**, only injected in code:
 
 ```typescript
-import { Schema, Context, Effect, Logger } from 'effect';
+import { Schema, Context, Effect } from 'effect';
 
 declare const generateId: () => string;
 
@@ -56,7 +56,7 @@ const createPaymentIntent = (amount: bigint) =>
 
 		// Use serial in business logic, logging, etc.
 		// but it's not part of the persisted data
-		yield* Logger.info(`Creating payment intent ${serial}`);
+		yield* Effect.logInfo(`Creating payment intent ${serial}`);
 
 		return PaymentIntent.make({ id: generateId(), amount });
 	});
@@ -177,7 +177,7 @@ Good fits:
 Witnesses are trivial to provide:
 
 ```typescript
-import { Effect } from 'effect';
+import { Context, Effect } from 'effect';
 
 declare const myProgram: Effect.Effect<unknown, never, Serial>;
 declare class Serial extends Context.Service<Serial, string>()('Serial') {}
@@ -188,7 +188,7 @@ const test = myProgram.pipe(Effect.provideService(Serial, 'test-serial-123'));
 Capabilities need implementation:
 
 ```typescript
-import { Effect } from 'effect';
+import { Context, Effect } from 'effect';
 
 declare const myProgram: Effect.Effect<unknown, never, SerialService>;
 declare class SerialService extends Context.Service<
@@ -217,7 +217,7 @@ const test = myProgram.pipe(
 - **Yes** → Keep in schema
 
 ```typescript
-import { Schema, Context, Effect, Logger, Clock } from 'effect';
+import { Schema, Context, Effect, Clock } from 'effect';
 
 declare const LineItem: Schema.Schema<any>;
 declare const generateId: () => string;
@@ -245,7 +245,7 @@ const createOrder = (items: Array<Schema.Schema.Type<typeof LineItem>>) =>
 		const requestId = yield* RequestId; // For logging
 		const timestamp = yield* Clock.currentTimeMillis; // For timestamp
 
-		yield* Logger.info({
+		yield* Effect.logInfo({
 			message: 'Creating order',
 			correlationId, // Used for tracing
 			requestId, // Used for logging