@warlock.js/logger 5.24.0 → 5.25.0

package/package.json

@@ -4,7 +4,7 @@
   "dependencies": {
     "@mongez/copper": "^2.1.3",
     "@mongez/reinforcements": "^4.0.2",
-    "@warlock.js/fs": "5.24.0",
+    "@warlock.js/fs": "5.25.0",
     "dayjs": "^1.11.9",
     "safe-stable-stringify": "^2.5.0"
   },
@@ -32,7 +32,7 @@
   "warlock": {
     "environment": "server"
   },
-  "version": "5.24.0",
+  "version": "5.25.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/capture-unhandled-errors/SKILL.md

@@ -1,111 +1,111 @@
----
-name: capture-unhandled-errors
-description: 'captureAnyUnhandledRejection() installs process.on(''unhandledRejection'') → log.error and process.on(''uncaughtException'') → log.fatal + process.exit(1) so process-level failures land in your channels and a fatal crash is never silently swallowed into exit 0. Triggers: `captureAnyUnhandledRejection`, `exitOnUncaughtException`, `unhandledRejection`, `uncaughtException`, `log.error`, `log.fatal`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "server exits 0 with no error", "silent exit / production server stopped", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `Sentry.init`, `@sentry/node`; native `process.on(''unhandledRejection'')`.'
----
-
-# Error capture — routing Node's unhandled errors through the logger
-
-`captureAnyUnhandledRejection()` installs two process-level listeners so crashes are logged — and, for an `uncaughtException`, made loud and terminal — instead of being silently swallowed.
-
-## What it does
-
-```ts
-import { captureAnyUnhandledRejection } from "@warlock.js/logger";
-
-captureAnyUnhandledRejection();
-```
-
-Registers:
-- `process.on("unhandledRejection", reason => log.error("app", "unhandledRejection", reason))` — logged; the process is kept alive.
-- `process.on("uncaughtException", error => log.fatal("app", "uncaughtException", error))` — logged, then `process.exit(1)` (by default).
-
-The split is intentional: an `uncaughtException` leaves the process in an undefined state, so it's semantically `fatal` and takes the process down. An `unhandledRejection` is a failure but not always process-ending (depends on Node's `--unhandled-rejections` policy and your app's recovery), so it stays at `error` and never exits. This makes "page on fatal" alerting clean — only true crashes ring the pager.
-
-## Why it exits (and why that matters)
-
-Registering *any* `uncaughtException` listener **suppresses** Node's default "print the stack + exit non-zero." A listener that only logs therefore turns an unrecoverable crash into a silent `exit 0` — which is exactly how a config file that throws at boot can look like "the server started, then just stopped," with no error printed. So the handler restores the contract:
-
-- **Exits non-zero** after logging (`process.exit(1)`), following a best-effort, time-bounded `log.flush()` so buffered `FileLog` / `SentryLog` entries drain first. Opt out with `captureAnyUnhandledRejection({ exitOnUncaughtException: false })` where the process is expected to recover on its own (a dev server reloading via HMR).
-- **Falls back to `console.error`** when no terminal channel is configured yet — the early-boot window, before `log.configure(...)`, where `log.fatal` has nowhere visible to go. When a `ConsoleLog` is present it already prints the entry, so the fallback is skipped (no double output).
-
-> The framework wires this for you in `bootstrap()` as `captureAnyUnhandledRejection({ exitOnUncaughtException: Application.isProduction })` — production crashes loudly and non-zero, the dev server logs-and-continues so HMR can recover.
-
-## When to call it
-
-**Once**, at startup, **after** channels are registered. Typical place: immediately after your `log.configure({...})` call.
-
-```ts title="src/index.ts"
-import {
-  log,
-  ConsoleLog,
-  FileLog,
-  captureAnyUnhandledRejection,
-} from "@warlock.js/logger";
-
-log.configure({
-  channels: [new ConsoleLog(), new FileLog({ levels: ["error"] })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],   // ← important; see below
-});
-
-captureAnyUnhandledRejection();
-```
-
-## Flushing on the crash path
-
-The `uncaughtException` handler runs a best-effort, time-bounded `log.flush()` **before** its own `process.exit(1)`, so buffered `FileLog` / `SentryLog` entries drain even though `process.exit()` skips `beforeExit`. You don't need `autoFlushOn: ["beforeExit"]` for the fatal entry to survive — the handler already drains.
-
-`"beforeExit"` in `autoFlushOn` is still worth setting for the *other* exit routes (a natural drain when the event loop empties on its own). For signal-driven shutdown (`SIGINT` / `SIGTERM`), include those signals in `autoFlushOn`. See [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
-
-## Idempotency — don't call it twice
-
-Calling `captureAnyUnhandledRejection()` a second time registers a second pair of listeners. Your next rejection gets logged twice. There's no dedup; just call it once.
-
-## What it does **not** do
-
-- **Does not swallow a fatal error.** After an `uncaughtException` it records the error, then exits non-zero itself — restoring Node's own default, which merely registering the listener would otherwise suppress. Pass `{ exitOnUncaughtException: false }` only when the process is meant to survive (e.g. HMR).
-- **Does not exit on an `unhandledRejection`.** That path only logs (at `error`); the process keeps running. Set Node's `--unhandled-rejections=throw` if you want a rejection to escalate to an `uncaughtException`.
-- **Does not install Node's `--unhandled-rejections` policy.** That's a Node flag; set it in your launch script if you want strict mode.
-- **Does not hook `SIGTERM` / `SIGINT`** — use `enableAutoFlush` for signal flushes.
-- **Does not filter.** Every rejection is logged at `error` and every uncaught exception at `fatal`, both with `module: "app"`. Filter per-channel if some noise slips in.
-
-## Checking an error was captured in tests
-
-Don't mock `process.on` — use a capturing channel and emit the listener directly:
-
-```ts
-import { log, captureAnyUnhandledRejection, LogChannel } from "@warlock.js/logger";
-import type { LoggingData } from "@warlock.js/logger";
-
-class Capture extends LogChannel {
-  public name = "capture";
-  public received: LoggingData[] = [];
-  public log(data: LoggingData) { this.received.push({ ...data }); }
-}
-
-it("routes unhandled rejections to the logger", async () => {
-  const capture = new Capture();
-  const originalChannels = log.channels;
-  log.channels = [capture];
-
-  captureAnyUnhandledRejection();
-  process.emit("unhandledRejection", new Error("boom"), Promise.resolve());
-
-  await new Promise((r) => setTimeout(r, 0));
-
-  expect(capture.received[0]!.module).toBe("app");
-  expect(capture.received[0]!.action).toBe("unhandledRejection");
-
-  log.channels = originalChannels;
-});
-```
-
-Testing the **`uncaughtException`** path additionally trips `process.exit(1)`, so stub it (`vi.spyOn(process, "exit").mockImplementation(() => undefined as never)`) or pass `{ exitOnUncaughtException: false }` — otherwise the emitted exception tears the test runner down. See [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md).
-
-## Module + action the capture uses
-
-Both listeners log with:
-- `module: "app"`
-- `action: "unhandledRejection"` (at `error`) or `action: "uncaughtException"` (at `fatal`)
-- `message`: the rejection reason / exception (keep it as the raw `Error` object — file channels capture the stack).
-
-If you want these routed to a specific file, filter on `data.module === "app"`. See [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md).
+---
+name: capture-unhandled-errors
+description: 'captureAnyUnhandledRejection() installs process.on(''unhandledRejection'') → log.error and process.on(''uncaughtException'') → log.fatal + process.exit(1) so process-level failures land in your channels and a fatal crash is never silently swallowed into exit 0. Triggers: `captureAnyUnhandledRejection`, `exitOnUncaughtException`, `unhandledRejection`, `uncaughtException`, `log.error`, `log.fatal`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "server exits 0 with no error", "silent exit / production server stopped", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `Sentry.init`, `@sentry/node`; native `process.on(''unhandledRejection'')`.'
+---
+
+# Error capture — routing Node's unhandled errors through the logger
+
+`captureAnyUnhandledRejection()` installs two process-level listeners so crashes are logged — and, for an `uncaughtException`, made loud and terminal — instead of being silently swallowed.
+
+## What it does
+
+```ts
+import { captureAnyUnhandledRejection } from "@warlock.js/logger";
+
+captureAnyUnhandledRejection();
+```
+
+Registers:
+- `process.on("unhandledRejection", reason => log.error("app", "unhandledRejection", reason))` — logged; the process is kept alive.
+- `process.on("uncaughtException", error => log.fatal("app", "uncaughtException", error))` — logged, then `process.exit(1)` (by default).
+
+The split is intentional: an `uncaughtException` leaves the process in an undefined state, so it's semantically `fatal` and takes the process down. An `unhandledRejection` is a failure but not always process-ending (depends on Node's `--unhandled-rejections` policy and your app's recovery), so it stays at `error` and never exits. This makes "page on fatal" alerting clean — only true crashes ring the pager.
+
+## Why it exits (and why that matters)
+
+Registering *any* `uncaughtException` listener **suppresses** Node's default "print the stack + exit non-zero." A listener that only logs therefore turns an unrecoverable crash into a silent `exit 0` — which is exactly how a config file that throws at boot can look like "the server started, then just stopped," with no error printed. So the handler restores the contract:
+
+- **Exits non-zero** after logging (`process.exit(1)`), following a best-effort, time-bounded `log.flush()` so buffered `FileLog` / `SentryLog` entries drain first. Opt out with `captureAnyUnhandledRejection({ exitOnUncaughtException: false })` where the process is expected to recover on its own (a dev server reloading via HMR).
+- **Falls back to `console.error`** when no terminal channel is configured yet — the early-boot window, before `log.configure(...)`, where `log.fatal` has nowhere visible to go. When a `ConsoleLog` is present it already prints the entry, so the fallback is skipped (no double output).
+
+> The framework wires this for you in `bootstrap()` as `captureAnyUnhandledRejection({ exitOnUncaughtException: Application.isProduction })` — production crashes loudly and non-zero, the dev server logs-and-continues so HMR can recover.
+
+## When to call it
+
+**Once**, at startup, **after** channels are registered. Typical place: immediately after your `log.configure({...})` call.
+
+```ts title="src/index.ts"
+import {
+  log,
+  ConsoleLog,
+  FileLog,
+  captureAnyUnhandledRejection,
+} from "@warlock.js/logger";
+
+log.configure({
+  channels: [new ConsoleLog(), new FileLog({ levels: ["error"] })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],   // ← important; see below
+});
+
+captureAnyUnhandledRejection();
+```
+
+## Flushing on the crash path
+
+The `uncaughtException` handler runs a best-effort, time-bounded `log.flush()` **before** its own `process.exit(1)`, so buffered `FileLog` / `SentryLog` entries drain even though `process.exit()` skips `beforeExit`. You don't need `autoFlushOn: ["beforeExit"]` for the fatal entry to survive — the handler already drains.
+
+`"beforeExit"` in `autoFlushOn` is still worth setting for the *other* exit routes (a natural drain when the event loop empties on its own). For signal-driven shutdown (`SIGINT` / `SIGTERM`), include those signals in `autoFlushOn`. See [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
+
+## Idempotency — don't call it twice
+
+Calling `captureAnyUnhandledRejection()` a second time registers a second pair of listeners. Your next rejection gets logged twice. There's no dedup; just call it once.
+
+## What it does **not** do
+
+- **Does not swallow a fatal error.** After an `uncaughtException` it records the error, then exits non-zero itself — restoring Node's own default, which merely registering the listener would otherwise suppress. Pass `{ exitOnUncaughtException: false }` only when the process is meant to survive (e.g. HMR).
+- **Does not exit on an `unhandledRejection`.** That path only logs (at `error`); the process keeps running. Set Node's `--unhandled-rejections=throw` if you want a rejection to escalate to an `uncaughtException`.
+- **Does not install Node's `--unhandled-rejections` policy.** That's a Node flag; set it in your launch script if you want strict mode.
+- **Does not hook `SIGTERM` / `SIGINT`** — use `enableAutoFlush` for signal flushes.
+- **Does not filter.** Every rejection is logged at `error` and every uncaught exception at `fatal`, both with `module: "app"`. Filter per-channel if some noise slips in.
+
+## Checking an error was captured in tests
+
+Don't mock `process.on` — use a capturing channel and emit the listener directly:
+
+```ts
+import { log, captureAnyUnhandledRejection, LogChannel } from "@warlock.js/logger";
+import type { LoggingData } from "@warlock.js/logger";
+
+class Capture extends LogChannel {
+  public name = "capture";
+  public received: LoggingData[] = [];
+  public log(data: LoggingData) { this.received.push({ ...data }); }
+}
+
+it("routes unhandled rejections to the logger", async () => {
+  const capture = new Capture();
+  const originalChannels = log.channels;
+  log.channels = [capture];
+
+  captureAnyUnhandledRejection();
+  process.emit("unhandledRejection", new Error("boom"), Promise.resolve());
+
+  await new Promise((r) => setTimeout(r, 0));
+
+  expect(capture.received[0]!.module).toBe("app");
+  expect(capture.received[0]!.action).toBe("unhandledRejection");
+
+  log.channels = originalChannels;
+});
+```
+
+Testing the **`uncaughtException`** path additionally trips `process.exit(1)`, so stub it (`vi.spyOn(process, "exit").mockImplementation(() => undefined as never)`) or pass `{ exitOnUncaughtException: false }` — otherwise the emitted exception tears the test runner down. See [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md).
+
+## Module + action the capture uses
+
+Both listeners log with:
+- `module: "app"`
+- `action: "unhandledRejection"` (at `error`) or `action: "uncaughtException"` (at `fatal`)
+- `message`: the rejection reason / exception (keep it as the raw `Error` object — file channels capture the stack).
+
+If you want these routed to a specific file, filter on `data.module === "app"`. See [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md).

package/skills/configure-logger/SKILL.md

@@ -1,105 +1,105 @@
----
-name: configure-logger
-description: 'Register channels via log.addChannel / log.setChannels / log.configure({channels, autoFlushOn, redact, minLevel}) at boot. Triggers: `log.configure`, `log.addChannel`, `log.setChannels`, `Logger`, `autoFlushOn`, `disableAutoFlush`; "wire channels at startup", "branch logger by NODE_ENV", "isolate a library''s logger", "replace channel list"; typical import `import { log, Logger, ConsoleLog, FileLog } from "@warlock.js/logger"`. Skip: channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; redaction — `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`; competing libs `winston.createLogger`, `pino`.'
----
-
-# Setup — registering channels at startup
-
-The logger is a singleton. Do all setup in one place, as early in the app entry point as possible.
-
-## The three channel-registration methods
-
-| Method | Semantics |
-|---|---|
-| `log.addChannel(channel)` | **Appends.** Safe to call multiple times. |
-| `log.setChannels([...])` | **Replaces** the full list. |
-| `log.configure({ channels, autoFlushOn, redact, minLevel })` | **Replaces** channels if provided; installs auto-flush if provided; sets redact / minLevel if provided. All four are optional. |
-
-All three return `this` — chainable.
-
-## Recommended pattern — one dedicated file
-
-```ts title="src/logger.ts"
-import { log, ConsoleLog, FileLog, JSONFileLog } from "@warlock.js/logger";
-
-if (process.env.NODE_ENV === "production") {
-  log.configure({
-    channels: [
-      new FileLog({ storagePath: "./storage/logs", chunk: "daily", rotate: true }),
-      new JSONFileLog({ storagePath: "./storage/logs-json", chunk: "daily" }),
-    ],
-    autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-  });
-} else if (process.env.NODE_ENV === "test") {
-  log.setChannels([]);   // silence logger during tests
-} else {
-  log.setChannels([new ConsoleLog()]);
-}
-```
-
-Import it once at the top of `src/index.ts`:
-
-```ts title="src/index.ts"
-import "./logger";                     // side-effect: configures singleton
-import { log } from "@warlock.js/logger";
-
-log.info("app", "start", "Server listening on :3000");
-```
-
-## What `configure({ autoFlushOn })` does
-
-Registers one process-level handler per event that calls `log.flushSync()` before Node exits. See [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) for the full behavior table.
-
-```ts
-log.configure({
-  channels: [new FileLog()],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-});
-// Now a buffered FileLog flushes on Ctrl+C, container stop, and natural exit.
-```
-
-Calling `configure({ autoFlushOn })` a second time **replaces** previous handlers (not stacks them). Call `log.disableAutoFlush()` to tear them down.
-
-## Creating an isolated Logger
-
-Rarely needed. Useful when a library wants its own channel list that doesn't share with the host app:
-
-```ts
-import { Logger, ConsoleLog } from "@warlock.js/logger";
-
-export const libraryLogger = new Logger();
-libraryLogger.addChannel(new ConsoleLog({ filter: (d) => d.module === "my-lib" }));
-```
-
-Every `new Logger()` gets a unique `id` (string, prefixed `"logger-"`).
-
-## Order matters — ANSI stripping across channels
-
-`Logger.log` shallow-clones the entry per non-terminal channel before stripping ANSI codes. Registering a terminal channel (ConsoleLog) **after** a non-terminal one (FileLog) still works — ConsoleLog sees the original colored message. But if you register them in reverse and add a channel that mutates `data` in place, the non-terminal channel will see the terminal channel's version. Prefer the built-ins; custom channels should not mutate `data`.
-
-## When to call what
-
-- **`addChannel`** — most common. Add channels as you discover you need them during setup.
-- **`setChannels`** — when env branching makes the full list clear at once (production vs dev).
-- **`configure`** — when you also want to install auto-flush, redact, or minLevel in the same call.
-
-## Combining everything
-
-```ts
-log.configure({
-  channels: [
-    new ConsoleLog({ showContext: true }),
-    new FileLog({ chunk: "daily" }),
-  ],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-  redact: { paths: ["context.password", "context.headers.authorization"] },
-  minLevel: process.env.LOG_LEVEL === "debug" ? "debug" : "info",
-});
-```
-
-See [`@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md) for the redact contract and [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) for `minLevel`.
-
-## See also
-
-- [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md) — what each built-in channel does
-- [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) — `autoFlushOn` event behavior
+---
+name: configure-logger
+description: 'Register channels via log.addChannel / log.setChannels / log.configure({channels, autoFlushOn, redact, minLevel}) at boot. Triggers: `log.configure`, `log.addChannel`, `log.setChannels`, `Logger`, `autoFlushOn`, `disableAutoFlush`; "wire channels at startup", "branch logger by NODE_ENV", "isolate a library''s logger", "replace channel list"; typical import `import { log, Logger, ConsoleLog, FileLog } from "@warlock.js/logger"`. Skip: channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; redaction — `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`; competing libs `winston.createLogger`, `pino`.'
+---
+
+# Setup — registering channels at startup
+
+The logger is a singleton. Do all setup in one place, as early in the app entry point as possible.
+
+## The three channel-registration methods
+
+| Method | Semantics |
+|---|---|
+| `log.addChannel(channel)` | **Appends.** Safe to call multiple times. |
+| `log.setChannels([...])` | **Replaces** the full list. |
+| `log.configure({ channels, autoFlushOn, redact, minLevel })` | **Replaces** channels if provided; installs auto-flush if provided; sets redact / minLevel if provided. All four are optional. |
+
+All three return `this` — chainable.
+
+## Recommended pattern — one dedicated file
+
+```ts title="src/logger.ts"
+import { log, ConsoleLog, FileLog, JSONFileLog } from "@warlock.js/logger";
+
+if (process.env.NODE_ENV === "production") {
+  log.configure({
+    channels: [
+      new FileLog({ storagePath: "./storage/logs", chunk: "daily", rotate: true }),
+      new JSONFileLog({ storagePath: "./storage/logs-json", chunk: "daily" }),
+    ],
+    autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+  });
+} else if (process.env.NODE_ENV === "test") {
+  log.setChannels([]);   // silence logger during tests
+} else {
+  log.setChannels([new ConsoleLog()]);
+}
+```
+
+Import it once at the top of `src/index.ts`:
+
+```ts title="src/index.ts"
+import "./logger";                     // side-effect: configures singleton
+import { log } from "@warlock.js/logger";
+
+log.info("app", "start", "Server listening on :3000");
+```
+
+## What `configure({ autoFlushOn })` does
+
+Registers one process-level handler per event that calls `log.flushSync()` before Node exits. See [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) for the full behavior table.
+
+```ts
+log.configure({
+  channels: [new FileLog()],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+// Now a buffered FileLog flushes on Ctrl+C, container stop, and natural exit.
+```
+
+Calling `configure({ autoFlushOn })` a second time **replaces** previous handlers (not stacks them). Call `log.disableAutoFlush()` to tear them down.
+
+## Creating an isolated Logger
+
+Rarely needed. Useful when a library wants its own channel list that doesn't share with the host app:
+
+```ts
+import { Logger, ConsoleLog } from "@warlock.js/logger";
+
+export const libraryLogger = new Logger();
+libraryLogger.addChannel(new ConsoleLog({ filter: (d) => d.module === "my-lib" }));
+```
+
+Every `new Logger()` gets a unique `id` (string, prefixed `"logger-"`).
+
+## Order matters — ANSI stripping across channels
+
+`Logger.log` shallow-clones the entry per non-terminal channel before stripping ANSI codes. Registering a terminal channel (ConsoleLog) **after** a non-terminal one (FileLog) still works — ConsoleLog sees the original colored message. But if you register them in reverse and add a channel that mutates `data` in place, the non-terminal channel will see the terminal channel's version. Prefer the built-ins; custom channels should not mutate `data`.
+
+## When to call what
+
+- **`addChannel`** — most common. Add channels as you discover you need them during setup.
+- **`setChannels`** — when env branching makes the full list clear at once (production vs dev).
+- **`configure`** — when you also want to install auto-flush, redact, or minLevel in the same call.
+
+## Combining everything
+
+```ts
+log.configure({
+  channels: [
+    new ConsoleLog({ showContext: true }),
+    new FileLog({ chunk: "daily" }),
+  ],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+  redact: { paths: ["context.password", "context.headers.authorization"] },
+  minLevel: process.env.LOG_LEVEL === "debug" ? "debug" : "info",
+});
+```
+
+See [`@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md) for the redact contract and [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) for `minLevel`.
+
+## See also
+
+- [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md) — what each built-in channel does
+- [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) — `autoFlushOn` event behavior