@warlock.js/logger 5.24.0 → 5.25.0

package/llms-full.txt

@@ -6,471 +6,471 @@
 
 ## capture-unhandled-errors  `@warlock.js/logger/capture-unhandled-errors/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).
+---
+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).
 
 
 ## configure-logger  `@warlock.js/logger/configure-logger/SKILL.md`
 
----
-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
 
 
 ## filter-log-entries  `@warlock.js/logger/filter-log-entries/SKILL.md`
 
----
-name: filter-log-entries
-description: 'Drop log entries — per-channel levels whitelist, per-channel filter predicate, logger-wide setMinLevel(level) fast path. Triggers: `levels`, `filter`, `minLevel`, `log.setMinLevel`, `shouldBeLogged`, `LoggingData`, `LogLevel`; "silence a noisy module", "route errors to a dedicated file", "raise global severity floor", "drop debug logs in prod"; typical import `import { log } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.'
----
-
-# Filtering — `levels` + `filter` predicate + `minLevel`
-
-Every channel can silently drop entries it doesn't care about. Three mechanisms stack: a logger-wide `minLevel` floor (cheapest), then per-channel `levels` whitelist, then per-channel `filter` predicate.
-
-## 1. `levels` — the per-channel whitelist
-
-```ts
-new FileLog({ levels: ["error", "warn"] });
-// debug/info/success entries → skipped
-// error/warn entries → written
-```
-
-- Omitting `levels` (or passing `[]`) means **allow all six**.
-- No regex / no range — it's a literal whitelist of `LogLevel` strings.
-
-## 2. `filter` — the per-channel custom predicate
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.module !== "healthcheck",
-});
-// Every entry is passed to the predicate; return false → skip.
-```
-
-- `data` is the full `LoggingData`: `{ type, module, action, message, context? }`.
-- Predicate runs **after** `levels` — an entry blocked by `levels` never reaches `filter`.
-
-## 3. `minLevel` — the logger-wide severity floor
-
-For the common "drop everything below X" case, skip the per-channel `levels` array and use the logger-wide fast path:
-
-```ts
-log.setMinLevel("info");
-// debug entries are dropped before fan-out — no channel ever sees them.
-
-log.configure({ minLevel: "warn" });   // shorthand inside configure()
-```
-
-Severity ordering: `debug < info ≈ success < warn < error < fatal`. `success` is treated as informational severity — `setMinLevel("warn")` drops it. `fatal` is strictly above `error`, so `setMinLevel("fatal")` admits only fatal entries (handy for "page me only on fatal" routing).
-
-Pass `undefined` to clear:
-
-```ts
-log.setMinLevel(undefined);   // accept everything again
-```
-
-This runs **before** the channel loop — cheaper than per-channel `levels` filters when you want a uniform floor. Per-channel `levels` and `filter` still run on top for channels that need a tighter or differently-shaped rule.
-
-## Combining — real patterns
-
-### Route errors to a dedicated file
-
-```ts
-log.setChannels([
-  new ConsoleLog(),
-  new FileLog({
-    name: "errors",
-    levels: ["error", "warn"],
-    chunk: "daily",
-  }),
-]);
-// ConsoleLog sees everything; errors.log only grows with warnings and errors.
-```
-
-### Silence a noisy module
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.module !== "socket.io",
-});
-```
-
-### Keep the dev terminal focused
-
-```ts
-// Only surface the subsystem you're actively working on
-new ConsoleLog({
-  filter: (data) => data.module === "auth",
-});
-```
-
-### Errors always pass, info only for one module
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.type === "error" || data.module === "payments",
-});
-```
-
-## Where filtering happens
-
-`LogChannel.shouldBeLogged(data)` runs both checks in order:
-
-```ts
-// levels check — fast path
-if (this.config("levels")?.length && !this.config("levels").includes(data.type)) return false;
-
-// filter predicate — only runs if levels allowed it
-const filter = this.config("filter");
-if (filter) return filter(data);
-
-return true;
-```
-
-If you extend `LogChannel` to write a custom channel, call `this.shouldBeLogged(data)` first thing inside your `log(data)` method — you inherit both mechanisms for free. See [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md).
-
-## Logger-wide custom filtering — not a thing
-
-There is no `logger.setGlobalFilter()`. Each channel filters itself. If you want the same predicate everywhere, pass it to every channel constructor (or wrap your channels in a helper).
-
-## Performance note
-
-Filters run on **every** entry per channel. A synchronous, cheap predicate is fine. Avoid `await` inside — the channel receives a fully-formed `LoggingData` and the filter is sync-only (type: `(data: LoggingData) => boolean`).
-
-The `minLevel` check is the fastest of the three (single comparison before fan-out), so prefer it when "drop everything below X uniformly" matches your need.
+---
+name: filter-log-entries
+description: 'Drop log entries — per-channel levels whitelist, per-channel filter predicate, logger-wide setMinLevel(level) fast path. Triggers: `levels`, `filter`, `minLevel`, `log.setMinLevel`, `shouldBeLogged`, `LoggingData`, `LogLevel`; "silence a noisy module", "route errors to a dedicated file", "raise global severity floor", "drop debug logs in prod"; typical import `import { log } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.'
+---
+
+# Filtering — `levels` + `filter` predicate + `minLevel`
+
+Every channel can silently drop entries it doesn't care about. Three mechanisms stack: a logger-wide `minLevel` floor (cheapest), then per-channel `levels` whitelist, then per-channel `filter` predicate.
+
+## 1. `levels` — the per-channel whitelist
+
+```ts
+new FileLog({ levels: ["error", "warn"] });
+// debug/info/success entries → skipped
+// error/warn entries → written
+```
+
+- Omitting `levels` (or passing `[]`) means **allow all six**.
+- No regex / no range — it's a literal whitelist of `LogLevel` strings.
+
+## 2. `filter` — the per-channel custom predicate
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.module !== "healthcheck",
+});
+// Every entry is passed to the predicate; return false → skip.
+```
+
+- `data` is the full `LoggingData`: `{ type, module, action, message, context? }`.
+- Predicate runs **after** `levels` — an entry blocked by `levels` never reaches `filter`.
+
+## 3. `minLevel` — the logger-wide severity floor
+
+For the common "drop everything below X" case, skip the per-channel `levels` array and use the logger-wide fast path:
+
+```ts
+log.setMinLevel("info");
+// debug entries are dropped before fan-out — no channel ever sees them.
+
+log.configure({ minLevel: "warn" });   // shorthand inside configure()
+```
+
+Severity ordering: `debug < info ≈ success < warn < error < fatal`. `success` is treated as informational severity — `setMinLevel("warn")` drops it. `fatal` is strictly above `error`, so `setMinLevel("fatal")` admits only fatal entries (handy for "page me only on fatal" routing).
+
+Pass `undefined` to clear:
+
+```ts
+log.setMinLevel(undefined);   // accept everything again
+```
+
+This runs **before** the channel loop — cheaper than per-channel `levels` filters when you want a uniform floor. Per-channel `levels` and `filter` still run on top for channels that need a tighter or differently-shaped rule.
+
+## Combining — real patterns
+
+### Route errors to a dedicated file
+
+```ts
+log.setChannels([
+  new ConsoleLog(),
+  new FileLog({
+    name: "errors",
+    levels: ["error", "warn"],
+    chunk: "daily",
+  }),
+]);
+// ConsoleLog sees everything; errors.log only grows with warnings and errors.
+```
+
+### Silence a noisy module
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.module !== "socket.io",
+});
+```
+
+### Keep the dev terminal focused
+
+```ts
+// Only surface the subsystem you're actively working on
+new ConsoleLog({
+  filter: (data) => data.module === "auth",
+});
+```
+
+### Errors always pass, info only for one module
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.type === "error" || data.module === "payments",
+});
+```
+
+## Where filtering happens
+
+`LogChannel.shouldBeLogged(data)` runs both checks in order:
+
+```ts
+// levels check — fast path
+if (this.config("levels")?.length && !this.config("levels").includes(data.type)) return false;
+
+// filter predicate — only runs if levels allowed it
+const filter = this.config("filter");
+if (filter) return filter(data);
+
+return true;
+```
+
+If you extend `LogChannel` to write a custom channel, call `this.shouldBeLogged(data)` first thing inside your `log(data)` method — you inherit both mechanisms for free. See [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md).
+
+## Logger-wide custom filtering — not a thing
+
+There is no `logger.setGlobalFilter()`. Each channel filters itself. If you want the same predicate everywhere, pass it to every channel constructor (or wrap your channels in a helper).
+
+## Performance note
+
+Filters run on **every** entry per channel. A synchronous, cheap predicate is fine. Avoid `await` inside — the channel receives a fully-formed `LoggingData` and the filter is sync-only (type: `(data: LoggingData) => boolean`).
+
+The `minLevel` check is the fastest of the three (single comparison before fan-out), so prefer it when "drop everything below X uniformly" matches your need.
 
 
 ## flush-logs-on-shutdown  `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`
 
----
-name: flush-logs-on-shutdown
-description: 'Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: [''SIGINT'', ''SIGTERM'', ''beforeExit'']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — `@warlock.js/logger/capture-unhandled-errors/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing `pino.final`, `winston.end`; native `process.on(''exit'')`.'
----
-
-# Lifecycle — flushing buffered channels before exit
-
-`FileLog` and `JSONFileLog` buffer entries in memory. A process that exits without draining loses the buffer.
-
-## The easy way — `autoFlushOn`
-
-Tell the logger which process events should trigger a flush. It installs the handlers for you.
-
-```ts
-log.configure({
-  channels: [new ConsoleLog(), new FileLog({ chunk: "daily" })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-});
-```
-
-### What each event does
-
-| Event | Behavior |
-|---|---|
-| `SIGINT` / `SIGTERM` / `SIGHUP` / `SIGBREAK` / `SIGUSR2` | Flush → remove this handler → re-raise the signal so Node's default exit code runs (e.g. 130 for SIGINT). |
-| `beforeExit` | Flush in place. Node continues its natural exit. |
-
-### Default recommendation
-
-`["SIGINT", "SIGTERM", "beforeExit"]` covers:
-- Local `Ctrl+C` (SIGINT)
-- Container orchestrators (`docker stop`, Kubernetes sending SIGTERM)
-- Natural exit (Node finished all work)
-
-Add `"SIGHUP"` if you care about terminal disconnects. Add `"SIGUSR2"` if you use nodemon or pm2 restart.
-
-### Idempotency
-
-Calling `enableAutoFlush` twice **replaces** previous handlers — it does not stack. `disableAutoFlush()` removes every handler this logger instance registered; safe to call when nothing is registered.
-
-## The manual way — your own handler
-
-Use this when you need async work (close an HTTP server, drain a queue) **before** flushing:
-
-```ts
-async function gracefulShutdown() {
-  await httpServer.close();
-  await queue.drain();
-  log.flushSync();          // still sync — guarantees disk write before exit
-  process.exit(0);
-}
-
-process.once("SIGINT", gracefulShutdown);
-process.once("SIGTERM", gracefulShutdown);
-```
-
-**If you go manual for a signal, skip it in `autoFlushOn`** — otherwise both handlers fire and ours re-raises the signal mid-way through your async work.
-
-## Async drain — `log.flush()`
-
-`flushSync()` blocks the event loop with synchronous I/O. That's correct for the file channels and required inside the handlers `autoFlushOn` installs (a re-raised signal kills the process before any promise could settle). But a channel whose delivery is **async** — a network transport, an async disk write — can't drain synchronously. For those, `await` the async sibling on a graceful path you control:
-
-```ts
-async function gracefulShutdown() {
-  await httpServer.close();
-  await log.flush();        // awaits every channel's async flush() to completion
-  process.exit(0);
-}
-
-process.once("SIGTERM", gracefulShutdown);
-```
-
-`log.flush()` fans out to every channel that implements `flush()` and awaits them together (`Promise.allSettled`). Each channel is isolated — one channel's flush rejecting neither aborts the others nor escapes as an unhandled rejection. Channels without `flush()` are skipped.
-
-| | `flushSync()` | `flush()` |
-|---|---|---|
-| I/O | synchronous — blocks the loop | asynchronous — awaited |
-| Safe in a re-raising signal handler | yes | no — the signal exits before the promise settles |
-| Used by `autoFlushOn` | yes | no |
-| Reach for it when | file channels, last-resort durability | network/async channels, manual `await` before `process.exit` |
-| `FileLog` / `JSONFileLog` | ✓ | ✓ (async write) |
-
-`autoFlushOn` always uses `flushSync()` — signal re-raising can't wait on a promise. If a channel needs async delivery on shutdown, drive `await log.flush()` from your own handler and leave that signal out of `autoFlushOn`.
-
-## What `flushSync()` actually does
-
-```ts
-log.flushSync();
-// For every registered channel:
-//   if (channel.flushSync) channel.flushSync();
-```
-
-- Synchronous I/O — blocks the event loop.
-- Channels without `flushSync` (e.g. `ConsoleLog` — nothing to flush) are skipped silently.
-- Works with and without `groupBy` on `FileLog` / `JSONFileLog`.
-- No-op if every channel's buffer is empty.
-
-`ConsoleLog` has no `flushSync` — it writes synchronously on every entry. `FileLog` and `JSONFileLog` both implement it.
-
-## Unhandled errors
-
-The `uncaughtException` path in [`captureAnyUnhandledRejection()`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) already runs a best-effort, time-bounded `log.flush()` before its own `process.exit(1)`, so the fatal entry drains without extra wiring (and `process.exit()` skips `beforeExit`, so a `beforeExit` handler would not fire on that path anyway). Still set `autoFlushOn` for the *other* shutdown routes — `"SIGINT"` / `"SIGTERM"` and a natural `"beforeExit"` — so those don't lose the last buffered batch.
-
-```ts
-log.configure({
-  channels: [new FileLog({ levels: ["error"] })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
-});
-
-captureAnyUnhandledRejection();
-```
-
-## What NOT to do
-
-- **Don't `await` inside a signal handler you wrote yourself and then call `flushSync`** — if an async step rejects, you skip the flush. Wrap in `try { await x } finally { log.flushSync(); process.exit(1); }`.
-- **Don't call `process.exit()` inside `autoFlushOn` handlers** — signal handlers here already re-raise the signal. Forcing an exit breaks exit codes.
-- **Don't rely on the 5-second flush interval for shutdown safety.** It's a throughput optimization, not a durability guarantee.
+---
+name: flush-logs-on-shutdown
+description: 'Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: [''SIGINT'', ''SIGTERM'', ''beforeExit'']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — `@warlock.js/logger/capture-unhandled-errors/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing `pino.final`, `winston.end`; native `process.on(''exit'')`.'
+---
+
+# Lifecycle — flushing buffered channels before exit
+
+`FileLog` and `JSONFileLog` buffer entries in memory. A process that exits without draining loses the buffer.
+
+## The easy way — `autoFlushOn`
+
+Tell the logger which process events should trigger a flush. It installs the handlers for you.
+
+```ts
+log.configure({
+  channels: [new ConsoleLog(), new FileLog({ chunk: "daily" })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+```
+
+### What each event does
+
+| Event | Behavior |
+|---|---|
+| `SIGINT` / `SIGTERM` / `SIGHUP` / `SIGBREAK` / `SIGUSR2` | Flush → remove this handler → re-raise the signal so Node's default exit code runs (e.g. 130 for SIGINT). |
+| `beforeExit` | Flush in place. Node continues its natural exit. |
+
+### Default recommendation
+
+`["SIGINT", "SIGTERM", "beforeExit"]` covers:
+- Local `Ctrl+C` (SIGINT)
+- Container orchestrators (`docker stop`, Kubernetes sending SIGTERM)
+- Natural exit (Node finished all work)
+
+Add `"SIGHUP"` if you care about terminal disconnects. Add `"SIGUSR2"` if you use nodemon or pm2 restart.
+
+### Idempotency
+
+Calling `enableAutoFlush` twice **replaces** previous handlers — it does not stack. `disableAutoFlush()` removes every handler this logger instance registered; safe to call when nothing is registered.
+
+## The manual way — your own handler
+
+Use this when you need async work (close an HTTP server, drain a queue) **before** flushing:
+
+```ts
+async function gracefulShutdown() {
+  await httpServer.close();
+  await queue.drain();
+  log.flushSync();          // still sync — guarantees disk write before exit
+  process.exit(0);
+}
+
+process.once("SIGINT", gracefulShutdown);
+process.once("SIGTERM", gracefulShutdown);
+```
+
+**If you go manual for a signal, skip it in `autoFlushOn`** — otherwise both handlers fire and ours re-raises the signal mid-way through your async work.
+
+## Async drain — `log.flush()`
+
+`flushSync()` blocks the event loop with synchronous I/O. That's correct for the file channels and required inside the handlers `autoFlushOn` installs (a re-raised signal kills the process before any promise could settle). But a channel whose delivery is **async** — a network transport, an async disk write — can't drain synchronously. For those, `await` the async sibling on a graceful path you control:
+
+```ts
+async function gracefulShutdown() {
+  await httpServer.close();
+  await log.flush();        // awaits every channel's async flush() to completion
+  process.exit(0);
+}
+
+process.once("SIGTERM", gracefulShutdown);
+```
+
+`log.flush()` fans out to every channel that implements `flush()` and awaits them together (`Promise.allSettled`). Each channel is isolated — one channel's flush rejecting neither aborts the others nor escapes as an unhandled rejection. Channels without `flush()` are skipped.
+
+| | `flushSync()` | `flush()` |
+|---|---|---|
+| I/O | synchronous — blocks the loop | asynchronous — awaited |
+| Safe in a re-raising signal handler | yes | no — the signal exits before the promise settles |
+| Used by `autoFlushOn` | yes | no |
+| Reach for it when | file channels, last-resort durability | network/async channels, manual `await` before `process.exit` |
+| `FileLog` / `JSONFileLog` | ✓ | ✓ (async write) |
+
+`autoFlushOn` always uses `flushSync()` — signal re-raising can't wait on a promise. If a channel needs async delivery on shutdown, drive `await log.flush()` from your own handler and leave that signal out of `autoFlushOn`.
+
+## What `flushSync()` actually does
+
+```ts
+log.flushSync();
+// For every registered channel:
+//   if (channel.flushSync) channel.flushSync();
+```
+
+- Synchronous I/O — blocks the event loop.
+- Channels without `flushSync` (e.g. `ConsoleLog` — nothing to flush) are skipped silently.
+- Works with and without `groupBy` on `FileLog` / `JSONFileLog`.
+- No-op if every channel's buffer is empty.
+
+`ConsoleLog` has no `flushSync` — it writes synchronously on every entry. `FileLog` and `JSONFileLog` both implement it.
+
+## Unhandled errors
+
+The `uncaughtException` path in [`captureAnyUnhandledRejection()`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) already runs a best-effort, time-bounded `log.flush()` before its own `process.exit(1)`, so the fatal entry drains without extra wiring (and `process.exit()` skips `beforeExit`, so a `beforeExit` handler would not fire on that path anyway). Still set `autoFlushOn` for the *other* shutdown routes — `"SIGINT"` / `"SIGTERM"` and a natural `"beforeExit"` — so those don't lose the last buffered batch.
+
+```ts
+log.configure({
+  channels: [new FileLog({ levels: ["error"] })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+
+captureAnyUnhandledRejection();
+```
+
+## What NOT to do
+
+- **Don't `await` inside a signal handler you wrote yourself and then call `flushSync`** — if an async step rejects, you skip the flush. Wrap in `try { await x } finally { log.flushSync(); process.exit(1); }`.
+- **Don't call `process.exit()` inside `autoFlushOn` handlers** — signal handlers here already re-raise the signal. Forcing an exit breaks exit codes.
+- **Don't rely on the 5-second flush interval for shutdown safety.** It's a throughput optimization, not a durability guarantee.
 
 
 ## logger-basics  `@warlock.js/logger/logger-basics/SKILL.md`
@@ -567,985 +567,985 @@ Every call signature is the same — `module`, `action`, `message`, optional `co
 
 ## overview  `@warlock.js/logger/overview/SKILL.md`
 
----
-name: overview
-description: "@warlock.js/logger overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/logger` — overview
-
-Structured logging for Node. Six severity levels (with `fatal` strictly above `error`), a singleton plus a `Logger` class, channel-based fan-out (one entry → many sinks), PII redaction as a floor that channels can extend, buffered file writes with signal-triggered flush on shutdown, an awaitable async `log.flush()` for network/async channels, an optional Sentry channel, and a couple of ergonomic helpers (`timer`, `assert`) that turn boilerplate into one-liners.
-
-Ships standalone — `@warlock.js/core` is not required. Drop it into any Node project.
-
-## Server-only package
-
+---
+name: overview
+description: "@warlock.js/logger overview for orientation and choosing the focused skill for the task."
+---
+
+# `@warlock.js/logger` — overview
+
+Structured logging for Node. Six severity levels (with `fatal` strictly above `error`), a singleton plus a `Logger` class, channel-based fan-out (one entry → many sinks), PII redaction as a floor that channels can extend, buffered file writes with signal-triggered flush on shutdown, an awaitable async `log.flush()` for network/async channels, an optional Sentry channel, and a couple of ergonomic helpers (`timer`, `assert`) that turn boilerplate into one-liners.
+
+Ships standalone — `@warlock.js/core` is not required. Drop it into any Node project.
+
+## Server-only package
+
 `@warlock.js/logger`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. This is build-boundary metadata read by `@warlock.js/web`'s Gate A (import resolution) and Gate C (emitted-bundle verification), not application behavior. App code that reaches the client bundle (including page and layout modules) must not value-import `@warlock.js/logger` — Gate A refuses the build. A type-only import (`import type { ... }`) is allowed. Server loaders, controllers, and modules may import it freely.
-
-## When to reach for it
-
-- Building a Node service that needs **structured** logs (key-value pairs, not bare strings) and you want them to land in multiple destinations (console for dev, JSON file for prod, third-party sink for audits) without rewriting the call sites.
-- You'd reach for **pino** or **winston** but want a smaller surface that's already wired into Warlock conventions (`module / action / message` shape, redaction floor, signal flush built-in).
-- Your team agrees that **`console.log` doesn't survive contact with production** — you need filtering, level routing, channel-specific sinks, and a redaction story before secrets leak into Slack/Datadog.
-
-Skip if your code is a throwaway script where `console.log` is genuinely fine — there's no value in adding a dependency for one-off logs.
-
-## The mental model in one paragraph
-
-You write `log.info("auth", "login", "user signed in", { userId })`. The logger fans that single entry out to every registered channel (`ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, or your custom subclass). Each channel decides whether to emit it (per-level whitelist, per-channel filter predicate, logger-wide minimum severity). Redaction runs once at the logger level and can be extended per channel — never relaxed. Buffered channels (file + JSON file) drain on flush — synchronously via `log.flushSync()` / `enableAutoFlush(['SIGINT', 'SIGTERM', 'beforeExit'])`, or asynchronously via `await log.flush()` (the only path that works for network channels like `SentryLog`). That's the whole package.
-
-## Skills index
-
-Eleven task skills cover everything. Load the one that matches your job — most callers only ever need `logger-basics` + `configure-logger` + `pick-log-channel`.
-
-### Foundations
-
-#### [`logger-basics`](@warlock.js/logger/logger-basics/SKILL.md)
-Start here. The `log` singleton, the six levels (`debug` / `info` / `warn` / `error` / `success` / `fatal`), how fan-out works, the `module / action / message / context` shape every entry carries.
-
-#### [`configure-logger`](@warlock.js/logger/configure-logger/SKILL.md)
-Wire channels at boot — `log.addChannel`, `log.setChannels`, `log.configure({ channels, autoFlushOn, redact, minLevel })`. Branch on `NODE_ENV`, replace the channel list, isolate a library's logger from the host singleton.
-
-### Channels
-
-#### [`pick-log-channel`](@warlock.js/logger/pick-log-channel/SKILL.md)
-Pick one of the four built-ins: `ConsoleLog` (terminal, colored), `FileLog` (plain `.log` on disk with rotation), `JSONFileLog` (structured JSON for aggregators — Datadog, Loki, ELK), `SentryLog` (errors + breadcrumbs to Sentry; `@sentry/node` is an optional peer).
-
-#### [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md)
-The `SentryLog` channel in depth — event-vs-breadcrumb level mapping, dual init modes (reuse an existing client or pass `options`), draining via `Sentry.flush(timeout)`, behavior when the optional peer isn't installed.
-
-#### [`write-custom-log-channel`](@warlock.js/logger/write-custom-log-channel/SKILL.md)
-Extend `LogChannel<Options>` for sinks the built-ins don't cover — Slack, HTTP endpoint, in-memory buffer, database. The lazy `init()` lifecycle (`setTimeout(0)`), the `terminal: true/false` ANSI-stripping behavior, and the difference between `flush()` (async, network) and `flushSync()` (sync, files) are subtle — read this skill before subclassing.
-
-### Production concerns
-
-#### [`redact-sensitive-log-fields`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md)
-Strip secrets before they reach a sink. Logger-wide `setRedact({ paths, censor })` is the security floor; per-channel `redact` configs add paths (never remove). Dotted-glob paths (`*`, `**`); censor as string or function `(value, path) => any`.
-
-#### [`filter-log-entries`](@warlock.js/logger/filter-log-entries/SKILL.md)
-Drop entries before they cost anything. Logger-wide `setMinLevel("info")` is the fast path; per-channel `levels` array + `filter` predicate for fine control.
-
-#### [`flush-logs-on-shutdown`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md)
-Buffered channels need explicit drain. `log.flushSync()` (sync) for file channels — also wired by `enableAutoFlush(['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK', 'SIGUSR2', 'beforeExit'])`. `await log.flush()` (async) for network/async channels like `SentryLog` — the only path that can await an HTTPS round-trip on a graceful shutdown.
-
-#### [`capture-unhandled-errors`](@warlock.js/logger/capture-unhandled-errors/SKILL.md)
-`captureAnyUnhandledRejection()` hooks `unhandledRejection` (→ `log.error("app", ...)`, process kept alive) and `uncaughtException` (→ `log.fatal("app", ...)` then `process.exit(1)` — restoring the non-zero exit the listener would otherwise suppress, so a fatal crash never becomes a silent `exit 0`; opt out with `{ exitOnUncaughtException: false }`). It flushes before exiting and falls back to `console.error` when no terminal channel is set. One call at startup.
-
-### Ergonomics + testing
-
-#### [`use-log-helpers`](@warlock.js/logger/use-log-helpers/SKILL.md)
-Two shortcuts every `Logger` exposes: `log.assert(condition, module, action, message, context?)` logs an error only when the condition is falsy (free on the happy path); `log.timer(module, action)` returns an end-function that emits `info` with a measured `durationMs`.
-
-#### [`test-logging-code`](@warlock.js/logger/test-logging-code/SKILL.md)
-Silence the logger globally in tests via `log.setChannels([])` in `setupFiles`. Assert specific entries with a capturing `LogChannel` subclass — it proves an entry was actually delivered through the pipeline (filters, redaction), not merely that a method was called, and it isolates cleanly by swapping `log.channels`.
-
-## Built-in channels at a glance
-
-| Channel | Sink | `terminal` | Buffered |
-| --- | --- | --- | --- |
-| `ConsoleLog` | `process.stdout` | `true` (colors kept) | no |
-| `FileLog` | `.log` files | `false` (ANSI stripped) | yes (5s timer or 100-entry buffer) |
-| `JSONFileLog` | `.json` files | `false` (ANSI stripped) | yes (same buffering) |
-| `SentryLog` | Sentry events + breadcrumbs | `false` | via the Sentry SDK's own transport (`@sentry/node` is an optional peer) |
-
-`terminal: true` is the flag that decides whether the channel sees raw colored messages or stripped plain text. Custom channels: pick `true` if you write to a terminal, `false` for anything else.
-
-## What this package deliberately doesn't do
-
-- **Distributed tracing.** Use OpenTelemetry. Logger gets you structured local logs with `module / action`; trace correlation is a different problem.
-- **Log aggregator integrations beyond Sentry.** `SentryLog` is bundled (with `@sentry/node` as an optional peer). For Datadog, Loki, ELK, etc., either write a custom channel that POSTs to the aggregator or use `JSONFileLog` + a sidecar (fluentbit, vector, promtail).
-- **Pretty-printing of arbitrary objects.** `ConsoleLog` has a `showContext` flag that runs `util.inspect` on the context object; for richer formatting, use `JSONFileLog` and view the file through your favorite viewer.
-- **Log analysis.** Querying / aggregating / alerting is on the sink side (Loki, ELK, Datadog).
-
-## See also
-
-- [`@warlock.js/core/warlock-conventions`](@warlock.js/core/warlock-conventions/SKILL.md) — the parent framework's conventions; logger is one of its foundation packages and ships transitively when you install core.
-- When synced via agent-kit, this `overview/SKILL.md` is flattened to the front-door skill `.claude/skills/warlock-js-logger-overview/` — every cross-link above uses the `@warlock.js/logger/<skill>/SKILL.md` name form so it survives that flattening.
+
+## When to reach for it
+
+- Building a Node service that needs **structured** logs (key-value pairs, not bare strings) and you want them to land in multiple destinations (console for dev, JSON file for prod, third-party sink for audits) without rewriting the call sites.
+- You'd reach for **pino** or **winston** but want a smaller surface that's already wired into Warlock conventions (`module / action / message` shape, redaction floor, signal flush built-in).
+- Your team agrees that **`console.log` doesn't survive contact with production** — you need filtering, level routing, channel-specific sinks, and a redaction story before secrets leak into Slack/Datadog.
+
+Skip if your code is a throwaway script where `console.log` is genuinely fine — there's no value in adding a dependency for one-off logs.
+
+## The mental model in one paragraph
+
+You write `log.info("auth", "login", "user signed in", { userId })`. The logger fans that single entry out to every registered channel (`ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, or your custom subclass). Each channel decides whether to emit it (per-level whitelist, per-channel filter predicate, logger-wide minimum severity). Redaction runs once at the logger level and can be extended per channel — never relaxed. Buffered channels (file + JSON file) drain on flush — synchronously via `log.flushSync()` / `enableAutoFlush(['SIGINT', 'SIGTERM', 'beforeExit'])`, or asynchronously via `await log.flush()` (the only path that works for network channels like `SentryLog`). That's the whole package.
+
+## Skills index
+
+Eleven task skills cover everything. Load the one that matches your job — most callers only ever need `logger-basics` + `configure-logger` + `pick-log-channel`.
+
+### Foundations
+
+#### [`logger-basics`](@warlock.js/logger/logger-basics/SKILL.md)
+Start here. The `log` singleton, the six levels (`debug` / `info` / `warn` / `error` / `success` / `fatal`), how fan-out works, the `module / action / message / context` shape every entry carries.
+
+#### [`configure-logger`](@warlock.js/logger/configure-logger/SKILL.md)
+Wire channels at boot — `log.addChannel`, `log.setChannels`, `log.configure({ channels, autoFlushOn, redact, minLevel })`. Branch on `NODE_ENV`, replace the channel list, isolate a library's logger from the host singleton.
+
+### Channels
+
+#### [`pick-log-channel`](@warlock.js/logger/pick-log-channel/SKILL.md)
+Pick one of the four built-ins: `ConsoleLog` (terminal, colored), `FileLog` (plain `.log` on disk with rotation), `JSONFileLog` (structured JSON for aggregators — Datadog, Loki, ELK), `SentryLog` (errors + breadcrumbs to Sentry; `@sentry/node` is an optional peer).
+
+#### [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md)
+The `SentryLog` channel in depth — event-vs-breadcrumb level mapping, dual init modes (reuse an existing client or pass `options`), draining via `Sentry.flush(timeout)`, behavior when the optional peer isn't installed.
+
+#### [`write-custom-log-channel`](@warlock.js/logger/write-custom-log-channel/SKILL.md)
+Extend `LogChannel<Options>` for sinks the built-ins don't cover — Slack, HTTP endpoint, in-memory buffer, database. The lazy `init()` lifecycle (`setTimeout(0)`), the `terminal: true/false` ANSI-stripping behavior, and the difference between `flush()` (async, network) and `flushSync()` (sync, files) are subtle — read this skill before subclassing.
+
+### Production concerns
+
+#### [`redact-sensitive-log-fields`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md)
+Strip secrets before they reach a sink. Logger-wide `setRedact({ paths, censor })` is the security floor; per-channel `redact` configs add paths (never remove). Dotted-glob paths (`*`, `**`); censor as string or function `(value, path) => any`.
+
+#### [`filter-log-entries`](@warlock.js/logger/filter-log-entries/SKILL.md)
+Drop entries before they cost anything. Logger-wide `setMinLevel("info")` is the fast path; per-channel `levels` array + `filter` predicate for fine control.
+
+#### [`flush-logs-on-shutdown`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md)
+Buffered channels need explicit drain. `log.flushSync()` (sync) for file channels — also wired by `enableAutoFlush(['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK', 'SIGUSR2', 'beforeExit'])`. `await log.flush()` (async) for network/async channels like `SentryLog` — the only path that can await an HTTPS round-trip on a graceful shutdown.
+
+#### [`capture-unhandled-errors`](@warlock.js/logger/capture-unhandled-errors/SKILL.md)
+`captureAnyUnhandledRejection()` hooks `unhandledRejection` (→ `log.error("app", ...)`, process kept alive) and `uncaughtException` (→ `log.fatal("app", ...)` then `process.exit(1)` — restoring the non-zero exit the listener would otherwise suppress, so a fatal crash never becomes a silent `exit 0`; opt out with `{ exitOnUncaughtException: false }`). It flushes before exiting and falls back to `console.error` when no terminal channel is set. One call at startup.
+
+### Ergonomics + testing
+
+#### [`use-log-helpers`](@warlock.js/logger/use-log-helpers/SKILL.md)
+Two shortcuts every `Logger` exposes: `log.assert(condition, module, action, message, context?)` logs an error only when the condition is falsy (free on the happy path); `log.timer(module, action)` returns an end-function that emits `info` with a measured `durationMs`.
+
+#### [`test-logging-code`](@warlock.js/logger/test-logging-code/SKILL.md)
+Silence the logger globally in tests via `log.setChannels([])` in `setupFiles`. Assert specific entries with a capturing `LogChannel` subclass — it proves an entry was actually delivered through the pipeline (filters, redaction), not merely that a method was called, and it isolates cleanly by swapping `log.channels`.
+
+## Built-in channels at a glance
+
+| Channel | Sink | `terminal` | Buffered |
+| --- | --- | --- | --- |
+| `ConsoleLog` | `process.stdout` | `true` (colors kept) | no |
+| `FileLog` | `.log` files | `false` (ANSI stripped) | yes (5s timer or 100-entry buffer) |
+| `JSONFileLog` | `.json` files | `false` (ANSI stripped) | yes (same buffering) |
+| `SentryLog` | Sentry events + breadcrumbs | `false` | via the Sentry SDK's own transport (`@sentry/node` is an optional peer) |
+
+`terminal: true` is the flag that decides whether the channel sees raw colored messages or stripped plain text. Custom channels: pick `true` if you write to a terminal, `false` for anything else.
+
+## What this package deliberately doesn't do
+
+- **Distributed tracing.** Use OpenTelemetry. Logger gets you structured local logs with `module / action`; trace correlation is a different problem.
+- **Log aggregator integrations beyond Sentry.** `SentryLog` is bundled (with `@sentry/node` as an optional peer). For Datadog, Loki, ELK, etc., either write a custom channel that POSTs to the aggregator or use `JSONFileLog` + a sidecar (fluentbit, vector, promtail).
+- **Pretty-printing of arbitrary objects.** `ConsoleLog` has a `showContext` flag that runs `util.inspect` on the context object; for richer formatting, use `JSONFileLog` and view the file through your favorite viewer.
+- **Log analysis.** Querying / aggregating / alerting is on the sink side (Loki, ELK, Datadog).
+
+## See also
+
+- [`@warlock.js/core/warlock-conventions`](@warlock.js/core/warlock-conventions/SKILL.md) — the parent framework's conventions; logger is one of its foundation packages and ships transitively when you install core.
+- When synced via agent-kit, this `overview/SKILL.md` is flattened to the front-door skill `.claude/skills/warlock-js-logger-overview/` — every cross-link above uses the `@warlock.js/logger/<skill>/SKILL.md` name form so it survives that flattening.
 
 
 ## pick-log-channel  `@warlock.js/logger/pick-log-channel/SKILL.md`
 
----
-name: pick-log-channel
-description: 'Pick one of the four built-in channels — ConsoleLog (terminal), FileLog (plain text on disk), JSONFileLog (structured JSON for aggregators like Loki / Datadog / Elastic), SentryLog (forwards errors + breadcrumbs to Sentry). Triggers: `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `chunk`, `rotate`, `groupBy`, `maxFileSize`, `showContext`, `log.channel`; "log to a file", "rotate log files", "daily log chunks", "json logs for datadog / loki / elastic", "send logs to Sentry"; typical import `import { ConsoleLog, FileLog, JSONFileLog, SentryLog } from "@warlock.js/logger"`. Skip: Sentry-specific setup — `@warlock.js/logger/ship-logs-to-sentry/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; registration — `@warlock.js/logger/configure-logger/SKILL.md`; competing libs `winston-daily-rotate-file`, `pino-pretty`.'
----
-
-# Channels — which one to pick and how to configure it
-
-Four built-in channels (`SentryLog` needs the optional `@sentry/node` peer). A channel is a destination for a log entry — the logger fans out every entry to every registered channel in parallel.
-
-## The decision
-
-| Need | Pick |
-|---|---|
-| Local dev, colored output in the terminal | `ConsoleLog` |
-| Plain text `.log` files on disk — humans read them | `FileLog` |
-| Structured `.json` files — a log aggregator (Loki / Datadog / Elastic) reads them | `JSONFileLog` |
-| Errors & warnings into Sentry (events + breadcrumbs) | `SentryLog` |
-
-Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
-
-## `ConsoleLog`
-
-Zero config. Colored, icon-prefixed lines to the terminal.
-
-```ts
-import { ConsoleLog } from "@warlock.js/logger";
-
-new ConsoleLog();
-// ⚙ debug (10:22:00.000) [auth] [hashPassword] Hashing started
-// ℹ info (10:22:01.482) [users] [register] New user created
-// ✗ error (10:22:03.111) [payments] [charge] Card declined
-```
-
-Properties:
-- `name = "console"`, `terminal = true`
-- Accepts `ConsoleLogConfig` — `levels`, `filter`, `dateFormat`, `showContext`, `contextDepth`
-- If `message` is an object, a second `console.log(message)` is issued so Node's inspector can expand it
-
-### Showing context
-
-By default `ConsoleLog` drops the `context` payload (the file/JSON channels still keep it). Flip `showContext: true` to render it on a second line — useful in development:
-
-```ts
-new ConsoleLog({ showContext: true });
-
-log.info("payments", "charge", "card declined", { userId: 42, amount: 1999 });
-// ℹ info (…) [payments] [charge] card declined
-//   ↳ { userId: 42, amount: 1999 }
-```
-
-Tune `contextDepth` (default `4`) to clamp how deep `util.inspect` recurses into nested objects.
-
-## `FileLog`
-
-Plain text. Buffers in memory, flushes to disk periodically.
-
-```ts
-import { FileLog } from "@warlock.js/logger";
-
-new FileLog({
-  storagePath: "./storage/logs",  // default: process.cwd() + "/storage/logs"
-  name: "app",                    // default: "app"
-  extension: "log",               // default: "log"
-  chunk: "daily",                 // "single" (default) | "daily" | "hourly"
-  rotate: true,                   // default: true
-  maxFileSize: 10 * 1024 * 1024,  // default: 10MB — triggers rotation
-  maxMessagesToWrite: 100,        // default: 100 — flush threshold
-  groupBy: ["level", "module"],   // optional subdirectory nesting
-});
-```
-
-Line format: `[date time] [level] [module][action]: message` — or a `[trace]` block when `message` is an `Error`.
-
-### Key gotchas
-
-- **Buffers!** Messages sit in memory until either `maxMessagesToWrite` is reached, 5 seconds pass, or `flushSync()` is called. A process that crashes without flushing loses buffered entries.
-- **`chunk: "daily"` picks a filename per day.** File name becomes `DD-MM-YYYY.log`. Combined with `rotate: true`, rotated archives get `Date.now()` suffixed.
-- **`groupBy` nests directories.** `groupBy: ["level", "module"]` produces `storage/logs/error/payments/app.log`. Order matters.
-- **Dispose channels you discard.** A live `FileLog` keeps a 5-second flush interval running. If you swap the channel list at runtime (reconfigure the logger), call `channel.dispose()` on the old instance — it clears that timer and drains the buffer one last time. Skipping it leaks one timer per discarded channel and keeps the event loop alive. (Channels that live for the whole process don't need this — process exit clears the timer.)
-
-## `JSONFileLog`
-
-Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output is a JSON object with a `messages` array:
-
-```json
-{
-  "messages": [
-    {
-      "content": "Card declined",
-      "level": "error",
-      "date": "15-03-2024 10:22:03",
-      "module": "payments",
-      "action": "charge",
-      "stack": [
-        "Error: Card declined",
-        "    at chargeCard (/app/src/payments.ts:42:11)"
-      ]
-    }
-  ]
-}
-```
-
-Differences from `FileLog`:
-- `name = "fileJson"` (**not** `"json"` — use this exact string for `log.channel("fileJson")`)
-- `extension` is always `"json"` — the option is silently ignored
-- Error `stack` is stored as `string[]` (split on newlines) — easy to query in aggregators
-- `content` holds the original user-supplied `message` (not a pre-formatted line)
-- Corrupted existing file → reinitialized to `{ messages: [] }` on next write (does not throw)
-- **Safe serialization by construction.** All writes go through `safe-stable-stringify` with a custom `Error` replacer — circular refs become `"[Circular]"`, BigInt is stringified, functions/symbols are dropped, nested `Error` instances expand to `{ name, message, stack, ...enumerable }`. A context payload with a class graph or circular reference will never throw during the write.
-
-## `SentryLog`
-
-Forwards entries to Sentry — `error` / `warn` become events (`captureException` for `Error` messages, `captureMessage` otherwise), every other level a breadcrumb (no quota). `@sentry/node` is an optional peer, lazily imported; pass an existing `client` or `options`.
-
-```ts
-import * as Sentry from "@sentry/node";
-import { SentryLog } from "@warlock.js/logger";
-
-new SentryLog({ client: Sentry, eventLevels: ["error", "warn"] });
-```
-
-Full guide — level mapping, init modes, shutdown draining: [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md).
-
-## Shared config — `BasicLogConfigurations`
-
-Every channel constructor accepts at minimum:
-
-```ts
-type BasicLogConfigurations = {
-  levels?: LogLevel[];                       // whitelist — omit or [] to allow all
-  filter?: (data: LoggingData) => boolean;   // custom predicate
-  dateFormat?: { date?: string; time?: string }; // Day.js format strings
-  context?: (data) => Promise<Record<string, any>>; // reserved — not yet read
-};
-```
-
-Concrete file channels extend this with their storage/chunk/rotate/groupBy options via intersection.
-
-## Picking a channel by name at runtime
-
-```ts
-log.channel("console");   // → ConsoleLog | undefined
-log.channel("file");      // → FileLog | undefined
-log.channel("fileJson");  // ← note the name — NOT "json"
-log.channel("sentry");    // → SentryLog | undefined
-```
-
-If two channels share a `name`, only one is reachable this way — the search returns the first match.
-
-## See also
-
-- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — registering channels at startup
-- [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) — `levels` and `filter` config in detail
-- [`@warlock.js/logger/ship-logs-to-sentry/SKILL.md`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md) — the `SentryLog` channel in depth
-- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — extending `LogChannel` for custom sinks
+---
+name: pick-log-channel
+description: 'Pick one of the four built-in channels — ConsoleLog (terminal), FileLog (plain text on disk), JSONFileLog (structured JSON for aggregators like Loki / Datadog / Elastic), SentryLog (forwards errors + breadcrumbs to Sentry). Triggers: `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `chunk`, `rotate`, `groupBy`, `maxFileSize`, `showContext`, `log.channel`; "log to a file", "rotate log files", "daily log chunks", "json logs for datadog / loki / elastic", "send logs to Sentry"; typical import `import { ConsoleLog, FileLog, JSONFileLog, SentryLog } from "@warlock.js/logger"`. Skip: Sentry-specific setup — `@warlock.js/logger/ship-logs-to-sentry/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; registration — `@warlock.js/logger/configure-logger/SKILL.md`; competing libs `winston-daily-rotate-file`, `pino-pretty`.'
+---
 
+# Channels — which one to pick and how to configure it
 
-## redact-sensitive-log-fields  `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`
+Four built-in channels (`SentryLog` needs the optional `@sentry/node` peer). A channel is a destination for a log entry — the logger fans out every entry to every registered channel in parallel.
 
----
-name: redact-sensitive-log-fields
-description: 'Strip secrets from log output — a built-in secret-key denylist on by default (DEFAULT_REDACT_KEYS), plus two-layer additive redaction via log.configure({redact: {paths, keys}}) (logger floor) + per-channel redact (more on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `keys`, `defaultKeys`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging", "turn off default redaction"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing libs `pino.redact`, `fast-redact`.'
----
-
-# Redaction — keeping secrets out of logs
-
-Three layers: a **built-in key denylist that is on by default**, plus opt-in path globs configured at the logger and/or per channel.
-
-## Layer 0 — the default denylist (since 4.15.0, no configuration needed)
-
-Common secret **key names** are censored at any depth of `context`, `message`, and an `Error`'s own enumerable properties — before any of your config runs:
-
-```ts
-log.error("auth", "login", "failed", { headers: req.headers, body: req.body });
-// context.headers.authorization → "[REDACTED]"
-// context.body.password         → "[REDACTED]"
-// context.body.email            → untouched
-```
-
-Keys are matched **exactly**, on a normalized form (lower-cased, separators stripped) — so one entry covers `apiKey` / `api_key` / `API-KEY` / `x-api-key`. It is not substring matching: `tokenCount` and `passwordUpdatedAt` survive. Read the exact set from `DEFAULT_REDACT_KEYS`.
-
-```ts
-import { DEFAULT_REDACT_KEYS } from "@warlock.js/logger";
-
-log.configure({
-  redact: {
-    keys: ["internalRef"],   // union with the built-in set
-    defaultKeys: false,      // opt out of the built-in set entirely
-  },
-});
-```
-
-`defaultKeys: false` is an escape hatch, not a tuning knob — it restores the pre-4.15.0 behavior where a `password` in `context` reaches every sink in cleartext. Prefer adding a function `censor` if you only need to keep a prefix.
-
-**A channel cannot turn the default set off** (it can only add keys, or turn it back *on* if the logger-wide config disabled it) — same additive-only contract as paths, below. And `log.setRedact(undefined)` clears *your* paths, not the default denylist.
-
-Not reachable by any layer: secrets interpolated into a `message` string (`` `token=${t}` ``), `Map`/`Set`/`Buffer` contents, and getter-backed or non-enumerable properties.
-
-## Layers 1 & 2 — path globs, opt-in
-
-For anything the denylist can't name by key — a secret under an app-specific key, or a value you want partially masked rather than blanked.
-
-The model in one line:
-
-> Logger-wide redaction is the security floor. Per-channel redaction adds more paths. **No channel can ever undo a logger-wide redaction.**
-
-That guarantee is the whole point — once you've set `password` to redact at the logger, you can audit one place to know nothing leaks it, regardless of how many channels you add.
-
-## Logger-wide floor
-
-```ts
-import { log } from "@warlock.js/logger";
-
-log.configure({
-  redact: {
-    paths: [
-      "context.password",
-      "context.*.token",
-      "context.headers.authorization",
-    ],
-    censor: "[REDACTED]",  // default — string or function
-  },
-});
-
-// runtime equivalent:
-log.setRedact({ paths: ["context.password"] });
-log.setRedact(undefined);  // clear your paths (the default denylist stays on)
-```
-
-Every channel sees the redacted entry. Cheap: applied **once** before fan-out; channels share the redacted clone unless they add their own paths.
-
-## Per-channel additive
-
-```ts
-new SlackChannel({
-  webhook: "...",
-  redact: {
-    paths: ["context.user.email", "context.metadata.*"],
-    // censor inherited from logger-wide when omitted
-  },
-});
-```
-
-The channel's `paths` are **merged** with the logger floor — the channel runs a single combined redact pass, never replaces the floor. The channel's `censor` (if provided) wins for both its own and the logger's paths in this channel only; the logger floor still uses its own censor for other channels.
-
-### When to set redact per-channel
-
-- Loud destinations with broader audiences (Slack, Discord, error trackers, anything off your machine) — redact more aggressively.
-- Local-only destinations (FileLog you alone read, the dev terminal) — keep the floor minimal so you can debug.
-
-### When NOT to set it
-
-If you want raw context in your dev terminal, **don't add redact at the logger level** — set it only on the file/JSON/network channels. Logger-wide is the floor, so it applies everywhere; you can't opt a single channel out.
-
-## Path syntax
-
-Paths are dotted glob patterns evaluated against the full `LoggingData`:
-
-```
-type LoggingData = {
-  type: "info" | ...,
-  module: string,
-  action: string,
-  message: any,        // ← prefix paths with "message." to redact here
-  context?: object,    // ← prefix paths with "context." to redact here
-};
-```
-
-| Pattern | Matches |
-| --- | --- |
-| `context.password` | exactly `data.context.password` |
-| `context.*.token` | `data.context.<any>.token` (one segment in between) |
-| `**.password` | `data.context.password`, `data.context.user.password`, … any depth |
-| `message.apiKey` | when message is an object, `data.message.apiKey` |
-| `context.users.*.token` | array element redaction (`*` matches indices too) |
-
-Wildcards:
-
-- `*` — exactly one segment (any object key, any array index).
-- `**` — zero or more segments, greedily; matches at any depth.
-
-## Censor variants
-
-```ts
-// String — replace with a literal.
-{ censor: "[REDACTED]" }
-{ censor: "***" }
-
-// Function — receives original value + dotted path, returns the replacement.
-{
-  censor: (value, path) => {
-    if (typeof value !== "string") return "[REDACTED]";
-    return value.length > 4 ? `${value.slice(0, 2)}***${value.slice(-2)}` : "***";
-  },
-}
-```
-
-Function censors are called for every match — keep them cheap. The path is the actual matched location (e.g. `"context.users.0.token"` for an array hit).
-
-## Immutability
-
-`applyRedact` always returns a deep clone — your input data is never mutated. `Date` and `Error` instances are reconstructed (so `instanceof` checks still work). Circular references are tolerated.
-
-## What about the `message` field?
-
-If `message` is a plain object, paths under `message.*` work as expected. If `message` is a string (the most common case), redaction won't scan it — string scrubbing requires regex and is out of scope for this primitive. Wrap secrets in `context` and they'll be redacted reliably.
-
-## Performance notes
-
-- **No redact configured** → the default denylist still runs (since 4.15.0): a cheap presence scan for a denylisted key on every `log()` call, with the deep clone + censor pass skipped entirely when nothing matches. Only `{ defaultKeys: false }` (no `paths`, no extra `keys`) gets back to zero work.
-- **Logger-wide redact only** → one deep clone + one path-walk per `log()` call, shared by every channel.
-- **Channel adds paths** → that channel re-clones from the original input and runs the merged pass once. Other channels still share the cheaper logger-wide clone.
-- Each path is matched independently; cost grows linearly with `paths.length`.
-
-For most apps with `<10` redact paths and shallow context, the cost is below 100µs per entry. If you're logging millions of entries per second through paths like `**.something`, profile before scaling up — `**` is the only pattern that recurses through every key.
+## The decision
 
+| Need | Pick |
+|---|---|
+| Local dev, colored output in the terminal | `ConsoleLog` |
+| Plain text `.log` files on disk — humans read them | `FileLog` |
+| Structured `.json` files — a log aggregator (Loki / Datadog / Elastic) reads them | `JSONFileLog` |
+| Errors & warnings into Sentry (events + breadcrumbs) | `SentryLog` |
 
-## ship-logs-to-sentry  `@warlock.js/logger/ship-logs-to-sentry/SKILL.md`
+Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
 
----
-name: ship-logs-to-sentry
-description: 'Forward log entries to Sentry with the SentryLog channel — error/warn become events (captureException/captureMessage), every other level a breadcrumb (no quota). @sentry/node is an OPTIONAL peer, lazily imported. Triggers: `SentryLog`, `@sentry/node`, `eventLevels`, `flushTimeout`, `Sentry.flush`, `captureException`, `addBreadcrumb`, `withScope`; "send logs to Sentry", "report errors to Sentry", "Sentry log channel", "Sentry breadcrumbs from logs", "log channel for Sentry"; typical import `import { SentryLog } from "@warlock.js/logger"`. Skip: file/console channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; graceful-shutdown flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; Slack alerting recipe.'
----
-
-# Ship logs to Sentry — the `SentryLog` channel
-
-`SentryLog` forwards log entries to Sentry. It's the one built-in channel that needs an external SDK, so `@sentry/node` is an **optional peer** — install it only if you use this channel:
-
-```bash
-npm install @sentry/node
-```
-
-## Two ways to wire it
-
-### Reuse an existing Sentry client (existing apps)
-
-If your app already calls `Sentry.init(...)`, pass the namespace as `client`. The channel forwards through it and never re-imports or re-initializes the SDK:
-
-```ts
-import * as Sentry from "@sentry/node";
-import { log, SentryLog } from "@warlock.js/logger";
-
-Sentry.init({ dsn: process.env.SENTRY_DSN, environment: "production" });
-
-log.addChannel(new SentryLog({ client: Sentry }));
-```
-
-### Let the channel initialize Sentry (new apps)
-
-Pass `options`; the channel lazily imports `@sentry/node` and calls `Sentry.init` once — guarded so it never clobbers an existing client:
-
-```ts
-import { log, SentryLog } from "@warlock.js/logger";
-
-log.addChannel(
-  new SentryLog({
-    options: {
-      dsn: process.env.SENTRY_DSN,
-      environment: process.env.NODE_ENV,
-      release: process.env.GIT_SHA,
-    },
-  }),
-);
-```
-
-With neither `client` nor `options`, the channel reuses whatever global Sentry client the host already initialized.
-
-## How levels map to Sentry
-
-This is the quota-control decision. Only `eventLevels` create Sentry **events** (which consume your error quota); every other level becomes a **breadcrumb** that rides along with the next event for free.
-
-| Logger level | Default | Sentry call |
-|---|---|---|
-| `fatal` | event | `captureException` for an `Error` message, else `captureMessage(…, "fatal")` |
-| `error` | event | `captureException` for an `Error` message, else `captureMessage(…, "error")` |
-| `warn` | event | `captureMessage(…, "warning")` |
-| `success` | breadcrumb | `addBreadcrumb({ level: "info" })` |
-| `info` | breadcrumb | `addBreadcrumb({ level: "info" })` |
-| `debug` | breadcrumb | `addBreadcrumb({ level: "debug" })` |
-
-- **Errors keep their stack.** A `message` that is an `Error` goes through `captureException`, so Sentry parses the real stack and groups correctly — never pre-stringify the error.
-- **`module` / `action` become tags** and the entry's `context` becomes a structured Sentry context, both scoped to that single event via `withScope`.
-- **`success` has no Sentry severity** — it's reported as `info`.
-
-### Tuning what becomes an event
-
-```ts
-// Only errors create events; warnings drop to breadcrumbs.
-new SentryLog({ client: Sentry, eventLevels: ["error"] });
-
-// Errors + warnings + an info stream as events (noisier, more quota).
-new SentryLog({ client: Sentry, eventLevels: ["error", "warn", "info"] });
-```
-
-`levels` and `filter` from `BasicLogConfigurations` apply first — a channel-level `levels: ["error", "warn"]` drops everything else before it reaches Sentry at all.
-
-## Draining on shutdown
-
-Sentry sends events asynchronously over the network, so a synchronous flush can't wait on them. `SentryLog.flush()` calls `Sentry.flush(timeout)`; drain it on your graceful-shutdown path:
-
-```ts
-async function shutdown() {
-  await httpServer.close();
-  await log.flush();   // SentryLog.flush() → Sentry.flush(flushTimeout)
-  process.exit(0);
-}
-
-process.once("SIGTERM", shutdown);
-```
-
-`flushTimeout` (default `2000` ms) bounds the wait so an unreachable Sentry can't hang shutdown. `autoFlushOn` uses the **synchronous** `flushSync()`, which does *not* drain Sentry — wire `await log.flush()` yourself. See [`flush-logs-on-shutdown`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
-
-## If `@sentry/node` isn't installed
-
-The channel never crashes your app: the dynamic import failure is swallowed, the install instructions are written to stderr **once**, and entries are dropped silently thereafter. So registering `SentryLog` in shared config is safe even in an environment where Sentry isn't installed.
-
-## Config reference
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `client` | Sentry namespace / forwarder | — | Reuse an already-initialized Sentry instance. |
-| `options` | `SentryInitOptions` | — | Sentry init options (mirrors `@sentry/node`'s `NodeOptions`) — used when the channel owns Sentry. |
-| `eventLevels` | `LogLevel[]` | `["fatal", "error", "warn"]` | Levels sent as events; the rest become breadcrumbs. |
-| `flushTimeout` | `number` | `2000` | Ms `flush()` waits for the transport to drain. |
-| `levels`, `filter`, `dateFormat`, `redact` | — | — | Inherited from `BasicLogConfigurations`. |
-
-## Don't do
-
-- **Don't double-init Sentry.** Pass *either* `client` *or* `options`, not both. The channel guards against double-init, but a single owner of `Sentry.init` is cleaner.
-- **Don't send every level as an event.** `eventLevels` with `info`/`debug`/`success` will flood your Sentry quota — keep them as breadcrumbs.
-- **Don't rely on `autoFlushOn` for Sentry.** It's synchronous; a network channel needs `await log.flush()`.
-
-## See also
-
-- [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) — `await log.flush()` on shutdown
-- [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md) — the console / file channels
-- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — build your own sink
+## `ConsoleLog`
 
+Zero config. Colored, icon-prefixed lines to the terminal.
 
-## test-logging-code  `@warlock.js/logger/test-logging-code/SKILL.md`
+```ts
+import { ConsoleLog } from "@warlock.js/logger";
+
+new ConsoleLog();
+// ⚙ debug (10:22:00.000) [auth] [hashPassword] Hashing started
+// ℹ info (10:22:01.482) [users] [register] New user created
+// ✗ error (10:22:03.111) [payments] [charge] Card declined
+```
 
----
-name: test-logging-code
-description: 'Test code that touches the logger — silence globally via log.setChannels([]) in setupFiles, assert specific log lines via a capturing LogChannel subclass (prefer it over vi.spyOn — it asserts on delivered entries, not just method calls, and isolates the shared singleton cleanly). Triggers: `log.setChannels`, `LogChannel`, `LoggingData`, `Logger`, `log.channels`; "silence logger in vitest", "assert a log line was emitted", "capture log output in tests", "test code that logs"; typical import `import { log, Logger, LogChannel, type LoggingData } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `vi.spyOn(console)`, `jest.spyOn`.'
----
-
-# Testing — code that logs, and asserting on log output
-
-Two scenarios: **silencing the logger during tests** (most common) and **asserting that a specific log line was emitted**.
-
-## Silence the logger during tests
-
-Clear every channel once, globally. No output, no file handles, no noise.
-
-```ts title="src/setupTests.ts"
-import { log } from "@warlock.js/logger";
-
-log.setChannels([]);
-```
-
-Wire it in Vitest:
-
-```ts title="vitest.config.ts"
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    setupFiles: ["src/setupTests.ts"],
-  },
-});
-```
-
-## Assert on log output — use a capturing channel
-
-Don't spy on `console.log` and don't mock `log.info` — assert on what a channel actually received instead (see "Why not spy on `log.info`?" below). The cleanest pattern is a tiny channel that records what it sees:
-
-```ts
-import { LogChannel } from "@warlock.js/logger";
-import type { LoggingData } from "@warlock.js/logger";
-
-class CapturingChannel extends LogChannel {
-  public name = "capture";
-  public terminal = false;
-  public received: LoggingData[] = [];
-  public log(data: LoggingData) { this.received.push({ ...data }); }
-}
-```
-
-### Test against the singleton
-
-```ts
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { log } from "@warlock.js/logger";
-import { createUser } from "./users";
-
-describe("createUser", () => {
-  let capture: CapturingChannel;
-  let originalChannels: typeof log.channels;
-
-  beforeEach(() => {
-    capture = new CapturingChannel();
-    originalChannels = log.channels;
-    log.channels = [capture];
-  });
-
-  afterEach(() => {
-    log.channels = originalChannels;
-  });
-
-  it("logs a success entry when the user is created", async () => {
-    await createUser({ email: "a@b.com" });
-
-    expect(capture.received).toContainEqual(
-      expect.objectContaining({
-        type: "success",
-        module: "users",
-        action: "create",
-      }),
-    );
-  });
-});
-```
-
-### Test an isolated logger (avoid touching the singleton)
-
-If the code under test accepts a logger via injection, create one per test:
-
-```ts
-import { Logger } from "@warlock.js/logger";
-
-const testLogger = new Logger();
-const capture = new CapturingChannel();
-testLogger.addChannel(capture);
-
-await createUser({ email: "a@b.com" }, testLogger);
-
-expect(capture.received[0]!.type).toBe("success");
-```
-
-No cleanup needed — the local `Logger` is garbage-collected.
-
-## Why not spy on `log.info`?
-
-`log` is a plain `Logger` instance (`export const log = new Logger()`) and every level method lives on the prototype, so `vi.spyOn(log, "info")` *does* technically work. Prefer the capturing channel anyway:
-
-- A spy on `log.info` proves the method was **called**, not that an entry was **delivered** — it skips the whole pipeline (`minLevel` floor, redaction, per-channel `levels` / `filter`). A capturing channel asserts on the entry your code under test actually produced after all of that ran.
-- The `log` singleton is shared global state. A spy you forget to `mockRestore()` leaks into the next test; swapping `log.channels` and restoring it in `afterEach` is the same amount of code and isolates cleanly.
-- Code that logs through `log.error(...)` and the bare object form `log.log({ type, ... })` both land in channels, but only the level shortcut goes through `log.info` — a channel catches both.
-
-So capture through a channel as shown above; reach for a method spy only when you specifically want to assert "this exact shortcut was invoked".
-
-## Testing a custom channel
-
-Write specs against the channel directly; don't route through `Logger`:
-
-```ts
-import { describe, it, expect, vi } from "vitest";
-import { SlackLog } from "./slack-log";
-
-describe("SlackLog", () => {
-  it("skips non-error levels", async () => {
-    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response());
-
-    const channel = new SlackLog({ webhookUrl: "https://test", levels: ["error"] });
-    await channel.log({ type: "info", module: "x", action: "y", message: "z" });
-
-    expect(fetchSpy).not.toHaveBeenCalled();
-  });
-});
-```
-
-## Testing `FileLog` and `JSONFileLog`
-
-Use real temp directories — it's the only way to exercise file IO, rotation, chunking, and JSON I/O with fidelity:
-
-```ts
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { randomUUID } from "node:crypto";
-
-function tempDir() {
-  const dir = path.join(os.tmpdir(), "logger-test", randomUUID());
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
-}
-```
-
-Clean up in `afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))`.
-
-## Waiting for async init
-
-`LogChannel.init()` runs inside a `setTimeout(0)`. Before asserting on post-init behavior, yield once:
-
-```ts
-const channel = new FileLog({ storagePath: tempDir() });
-await new Promise((r) => setTimeout(r, 10));
-// Now `channel.isInitialized` is true and it's safe to call `channel.log(...)` for real I/O.
-```
-
-## Testing `captureAnyUnhandledRejection`
-
-Don't actually throw unhandled rejections in tests — emit the listener directly:
-
-```ts
-captureAnyUnhandledRejection();
-process.emit("unhandledRejection", new Error("test"), Promise.resolve());
-```
-
-The `uncaughtException` path additionally calls `process.exit(1)`, so stub it (or pass `{ exitOnUncaughtException: false }`) before emitting — otherwise the emitted exception tears the test runner down:
-
-```ts
-vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
-captureAnyUnhandledRejection();
-process.emit("uncaughtException", new Error("test"), "uncaughtException");
-```
-
-See [`@warlock.js/logger/capture-unhandled-errors/SKILL.md`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) for a full example.
+Properties:
+- `name = "console"`, `terminal = true`
+- Accepts `ConsoleLogConfig` — `levels`, `filter`, `dateFormat`, `showContext`, `contextDepth`
+- If `message` is an object, a second `console.log(message)` is issued so Node's inspector can expand it
 
+### Showing context
 
-## use-log-helpers  `@warlock.js/logger/use-log-helpers/SKILL.md`
+By default `ConsoleLog` drops the `context` payload (the file/JSON channels still keep it). Flip `showContext: true` to render it on a second line — useful in development:
+
+```ts
+new ConsoleLog({ showContext: true });
 
----
-name: use-log-helpers
-description: 'Two DX shortcuts on every Logger — log.assert(condition, module, action, message, context?) logs an error when condition is falsy (free on the happy path), log.timer(module, action) returns an end-function emitting an info entry with measured duration. Triggers: `log.assert`, `log.timer`, `durationMs`; "assert an invariant via logger", "measure how long an operation took", "time a request", "log operation duration"; typical import `import { log } from "@warlock.js/logger"`. Skip: basics — `@warlock.js/logger/logger-basics/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.'
----
-
-# Helpers — `assert`, `timer`
-
-Two small DX shortcuts on every `Logger` (and the bound `log` helper). They route through the normal log pipeline — every channel sees what they emit.
-
-## `log.assert(condition, module, action, message, context?)`
-
-Logs an `error` entry when `condition` is falsy. Genuinely free in the happy path: when the condition is truthy, the entry is never built and channels are never invoked.
-
-```ts
-log.assert(user !== null, "auth", "session", "user vanished mid-flight", {
-  sessionId,
-});
-
-// truthy → no log call
-// falsy  → equivalent to log.error("auth", "session", "user vanished...", { sessionId })
-```
-
-The level is implicitly `error` — assertions express failures, not warnings. If you need a non-error level, use `log.error` / `log.warn` directly with your own `if`.
-
-### Why not `console.assert`?
-
-`console.assert` writes to stderr only and bypasses your file/JSON channels. `log.assert` runs through the logger pipeline, so a failed assertion is captured by every persistent channel you've configured. See [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md).
-
-## `log.timer(module, action)`
-
-Returns an end-function. Calling it emits an `info` entry with `completed in <ms>ms` and a `durationMs` field in `context`.
-
-```ts
-const end = log.timer("db", "users.findById");
-const user = await usersRepo.findById(id);
-end({ id, found: !!user });
-// ℹ info [db] [users.findById] completed in 12ms
-//   ↳ { durationMs: 12, id: "abc", found: true } (when ConsoleLog has showContext: true)
-```
-
-Common patterns:
-
-```ts
-// Around an HTTP handler
-async function handle(req) {
-  const end = log.timer("http", `${req.method} ${req.url}`);
-  try {
-    return await runHandler(req);
-  } finally {
-    end({ status: res.statusCode });
-  }
-}
-
-// Around a job
-const end = log.timer("jobs", "nightly-report");
-await report.run();
-end({ rowsProcessed: report.rowCount });
-```
-
-`end()` can be called more than once if you want intermediate checkpoints — each call emits a fresh entry with the duration measured from the original `timer()` call.
-
-### Caveats
-
-- The duration is `Date.now()` based — millisecond resolution. For sub-millisecond profiling, reach for `performance.now()` directly.
-- The end-function captures `this` at construction; calling it after the logger is reconfigured still routes through the same `Logger` instance.
-- `log.timer` shorthand binds to the singleton — see [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md) for how to swap channels per test.
+log.info("payments", "charge", "card declined", { userId: 42, amount: 1999 });
+// ℹ info (…) [payments] [charge] card declined
+//   ↳ { userId: 42, amount: 1999 }
+```
 
+Tune `contextDepth` (default `4`) to clamp how deep `util.inspect` recurses into nested objects.
 
-## write-custom-log-channel  `@warlock.js/logger/write-custom-log-channel/SKILL.md`
+## `FileLog`
+
+Plain text. Buffers in memory, flushes to disk periodically.
+
+```ts
+import { FileLog } from "@warlock.js/logger";
+
+new FileLog({
+  storagePath: "./storage/logs",  // default: process.cwd() + "/storage/logs"
+  name: "app",                    // default: "app"
+  extension: "log",               // default: "log"
+  chunk: "daily",                 // "single" (default) | "daily" | "hourly"
+  rotate: true,                   // default: true
+  maxFileSize: 10 * 1024 * 1024,  // default: 10MB — triggers rotation
+  maxMessagesToWrite: 100,        // default: 100 — flush threshold
+  groupBy: ["level", "module"],   // optional subdirectory nesting
+});
+```
+
+Line format: `[date time] [level] [module][action]: message` — or a `[trace]` block when `message` is an `Error`.
+
+### Key gotchas
+
+- **Buffers!** Messages sit in memory until either `maxMessagesToWrite` is reached, 5 seconds pass, or `flushSync()` is called. A process that crashes without flushing loses buffered entries.
+- **`chunk: "daily"` picks a filename per day.** File name becomes `DD-MM-YYYY.log`. Combined with `rotate: true`, rotated archives get `Date.now()` suffixed.
+- **`groupBy` nests directories.** `groupBy: ["level", "module"]` produces `storage/logs/error/payments/app.log`. Order matters.
+- **Dispose channels you discard.** A live `FileLog` keeps a 5-second flush interval running. If you swap the channel list at runtime (reconfigure the logger), call `channel.dispose()` on the old instance — it clears that timer and drains the buffer one last time. Skipping it leaks one timer per discarded channel and keeps the event loop alive. (Channels that live for the whole process don't need this — process exit clears the timer.)
+
+## `JSONFileLog`
+
+Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output is a JSON object with a `messages` array:
+
+```json
+{
+  "messages": [
+    {
+      "content": "Card declined",
+      "level": "error",
+      "date": "15-03-2024 10:22:03",
+      "module": "payments",
+      "action": "charge",
+      "stack": [
+        "Error: Card declined",
+        "    at chargeCard (/app/src/payments.ts:42:11)"
+      ]
+    }
+  ]
+}
+```
+
+Differences from `FileLog`:
+- `name = "fileJson"` (**not** `"json"` — use this exact string for `log.channel("fileJson")`)
+- `extension` is always `"json"` — the option is silently ignored
+- Error `stack` is stored as `string[]` (split on newlines) — easy to query in aggregators
+- `content` holds the original user-supplied `message` (not a pre-formatted line)
+- Corrupted existing file → reinitialized to `{ messages: [] }` on next write (does not throw)
+- **Safe serialization by construction.** All writes go through `safe-stable-stringify` with a custom `Error` replacer — circular refs become `"[Circular]"`, BigInt is stringified, functions/symbols are dropped, nested `Error` instances expand to `{ name, message, stack, ...enumerable }`. A context payload with a class graph or circular reference will never throw during the write.
+
+## `SentryLog`
+
+Forwards entries to Sentry — `error` / `warn` become events (`captureException` for `Error` messages, `captureMessage` otherwise), every other level a breadcrumb (no quota). `@sentry/node` is an optional peer, lazily imported; pass an existing `client` or `options`.
+
+```ts
+import * as Sentry from "@sentry/node";
+import { SentryLog } from "@warlock.js/logger";
+
+new SentryLog({ client: Sentry, eventLevels: ["error", "warn"] });
+```
+
+Full guide — level mapping, init modes, shutdown draining: [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md).
+
+## Shared config — `BasicLogConfigurations`
+
+Every channel constructor accepts at minimum:
+
+```ts
+type BasicLogConfigurations = {
+  levels?: LogLevel[];                       // whitelist — omit or [] to allow all
+  filter?: (data: LoggingData) => boolean;   // custom predicate
+  dateFormat?: { date?: string; time?: string }; // Day.js format strings
+  context?: (data) => Promise<Record<string, any>>; // reserved — not yet read
+};
+```
+
+Concrete file channels extend this with their storage/chunk/rotate/groupBy options via intersection.
+
+## Picking a channel by name at runtime
+
+```ts
+log.channel("console");   // → ConsoleLog | undefined
+log.channel("file");      // → FileLog | undefined
+log.channel("fileJson");  // ← note the name — NOT "json"
+log.channel("sentry");    // → SentryLog | undefined
+```
+
+If two channels share a `name`, only one is reachable this way — the search returns the first match.
+
+## See also
+
+- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — registering channels at startup
+- [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) — `levels` and `filter` config in detail
+- [`@warlock.js/logger/ship-logs-to-sentry/SKILL.md`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md) — the `SentryLog` channel in depth
+- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — extending `LogChannel` for custom sinks
+
+
+## redact-sensitive-log-fields  `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`
+
+---
+name: redact-sensitive-log-fields
+description: 'Strip secrets from log output — a built-in secret-key denylist on by default (DEFAULT_REDACT_KEYS), plus two-layer additive redaction via log.configure({redact: {paths, keys}}) (logger floor) + per-channel redact (more on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `keys`, `defaultKeys`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging", "turn off default redaction"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing libs `pino.redact`, `fast-redact`.'
+---
+
+# Redaction — keeping secrets out of logs
+
+Three layers: a **built-in key denylist that is on by default**, plus opt-in path globs configured at the logger and/or per channel.
+
+## Layer 0 — the default denylist (since 4.15.0, no configuration needed)
+
+Common secret **key names** are censored at any depth of `context`, `message`, and an `Error`'s own enumerable properties — before any of your config runs:
+
+```ts
+log.error("auth", "login", "failed", { headers: req.headers, body: req.body });
+// context.headers.authorization → "[REDACTED]"
+// context.body.password         → "[REDACTED]"
+// context.body.email            → untouched
+```
+
+Keys are matched **exactly**, on a normalized form (lower-cased, separators stripped) — so one entry covers `apiKey` / `api_key` / `API-KEY` / `x-api-key`. It is not substring matching: `tokenCount` and `passwordUpdatedAt` survive. Read the exact set from `DEFAULT_REDACT_KEYS`.
+
+```ts
+import { DEFAULT_REDACT_KEYS } from "@warlock.js/logger";
+
+log.configure({
+  redact: {
+    keys: ["internalRef"],   // union with the built-in set
+    defaultKeys: false,      // opt out of the built-in set entirely
+  },
+});
+```
+
+`defaultKeys: false` is an escape hatch, not a tuning knob — it restores the pre-4.15.0 behavior where a `password` in `context` reaches every sink in cleartext. Prefer adding a function `censor` if you only need to keep a prefix.
+
+**A channel cannot turn the default set off** (it can only add keys, or turn it back *on* if the logger-wide config disabled it) — same additive-only contract as paths, below. And `log.setRedact(undefined)` clears *your* paths, not the default denylist.
+
+Not reachable by any layer: secrets interpolated into a `message` string (`` `token=${t}` ``), `Map`/`Set`/`Buffer` contents, and getter-backed or non-enumerable properties.
+
+## Layers 1 & 2 — path globs, opt-in
+
+For anything the denylist can't name by key — a secret under an app-specific key, or a value you want partially masked rather than blanked.
+
+The model in one line:
+
+> Logger-wide redaction is the security floor. Per-channel redaction adds more paths. **No channel can ever undo a logger-wide redaction.**
+
+That guarantee is the whole point — once you've set `password` to redact at the logger, you can audit one place to know nothing leaks it, regardless of how many channels you add.
+
+## Logger-wide floor
+
+```ts
+import { log } from "@warlock.js/logger";
+
+log.configure({
+  redact: {
+    paths: [
+      "context.password",
+      "context.*.token",
+      "context.headers.authorization",
+    ],
+    censor: "[REDACTED]",  // default — string or function
+  },
+});
+
+// runtime equivalent:
+log.setRedact({ paths: ["context.password"] });
+log.setRedact(undefined);  // clear your paths (the default denylist stays on)
+```
+
+Every channel sees the redacted entry. Cheap: applied **once** before fan-out; channels share the redacted clone unless they add their own paths.
+
+## Per-channel additive
+
+```ts
+new SlackChannel({
+  webhook: "...",
+  redact: {
+    paths: ["context.user.email", "context.metadata.*"],
+    // censor inherited from logger-wide when omitted
+  },
+});
+```
+
+The channel's `paths` are **merged** with the logger floor — the channel runs a single combined redact pass, never replaces the floor. The channel's `censor` (if provided) wins for both its own and the logger's paths in this channel only; the logger floor still uses its own censor for other channels.
+
+### When to set redact per-channel
+
+- Loud destinations with broader audiences (Slack, Discord, error trackers, anything off your machine) — redact more aggressively.
+- Local-only destinations (FileLog you alone read, the dev terminal) — keep the floor minimal so you can debug.
+
+### When NOT to set it
+
+If you want raw context in your dev terminal, **don't add redact at the logger level** — set it only on the file/JSON/network channels. Logger-wide is the floor, so it applies everywhere; you can't opt a single channel out.
+
+## Path syntax
+
+Paths are dotted glob patterns evaluated against the full `LoggingData`:
+
+```
+type LoggingData = {
+  type: "info" | ...,
+  module: string,
+  action: string,
+  message: any,        // ← prefix paths with "message." to redact here
+  context?: object,    // ← prefix paths with "context." to redact here
+};
+```
+
+| Pattern | Matches |
+| --- | --- |
+| `context.password` | exactly `data.context.password` |
+| `context.*.token` | `data.context.<any>.token` (one segment in between) |
+| `**.password` | `data.context.password`, `data.context.user.password`, … any depth |
+| `message.apiKey` | when message is an object, `data.message.apiKey` |
+| `context.users.*.token` | array element redaction (`*` matches indices too) |
+
+Wildcards:
+
+- `*` — exactly one segment (any object key, any array index).
+- `**` — zero or more segments, greedily; matches at any depth.
+
+## Censor variants
+
+```ts
+// String — replace with a literal.
+{ censor: "[REDACTED]" }
+{ censor: "***" }
+
+// Function — receives original value + dotted path, returns the replacement.
+{
+  censor: (value, path) => {
+    if (typeof value !== "string") return "[REDACTED]";
+    return value.length > 4 ? `${value.slice(0, 2)}***${value.slice(-2)}` : "***";
+  },
+}
+```
+
+Function censors are called for every match — keep them cheap. The path is the actual matched location (e.g. `"context.users.0.token"` for an array hit).
+
+## Immutability
+
+`applyRedact` always returns a deep clone — your input data is never mutated. `Date` and `Error` instances are reconstructed (so `instanceof` checks still work). Circular references are tolerated.
+
+## What about the `message` field?
+
+If `message` is a plain object, paths under `message.*` work as expected. If `message` is a string (the most common case), redaction won't scan it — string scrubbing requires regex and is out of scope for this primitive. Wrap secrets in `context` and they'll be redacted reliably.
+
+## Performance notes
+
+- **No redact configured** → the default denylist still runs (since 4.15.0): a cheap presence scan for a denylisted key on every `log()` call, with the deep clone + censor pass skipped entirely when nothing matches. Only `{ defaultKeys: false }` (no `paths`, no extra `keys`) gets back to zero work.
+- **Logger-wide redact only** → one deep clone + one path-walk per `log()` call, shared by every channel.
+- **Channel adds paths** → that channel re-clones from the original input and runs the merged pass once. Other channels still share the cheaper logger-wide clone.
+- Each path is matched independently; cost grows linearly with `paths.length`.
+
+For most apps with `<10` redact paths and shallow context, the cost is below 100µs per entry. If you're logging millions of entries per second through paths like `**.something`, profile before scaling up — `**` is the only pattern that recurses through every key.
+
+
+## ship-logs-to-sentry  `@warlock.js/logger/ship-logs-to-sentry/SKILL.md`
+
+---
+name: ship-logs-to-sentry
+description: 'Forward log entries to Sentry with the SentryLog channel — error/warn become events (captureException/captureMessage), every other level a breadcrumb (no quota). @sentry/node is an OPTIONAL peer, lazily imported. Triggers: `SentryLog`, `@sentry/node`, `eventLevels`, `flushTimeout`, `Sentry.flush`, `captureException`, `addBreadcrumb`, `withScope`; "send logs to Sentry", "report errors to Sentry", "Sentry log channel", "Sentry breadcrumbs from logs", "log channel for Sentry"; typical import `import { SentryLog } from "@warlock.js/logger"`. Skip: file/console channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; graceful-shutdown flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; Slack alerting recipe.'
+---
+
+# Ship logs to Sentry — the `SentryLog` channel
+
+`SentryLog` forwards log entries to Sentry. It's the one built-in channel that needs an external SDK, so `@sentry/node` is an **optional peer** — install it only if you use this channel:
+
+```bash
+npm install @sentry/node
+```
+
+## Two ways to wire it
+
+### Reuse an existing Sentry client (existing apps)
+
+If your app already calls `Sentry.init(...)`, pass the namespace as `client`. The channel forwards through it and never re-imports or re-initializes the SDK:
+
+```ts
+import * as Sentry from "@sentry/node";
+import { log, SentryLog } from "@warlock.js/logger";
+
+Sentry.init({ dsn: process.env.SENTRY_DSN, environment: "production" });
+
+log.addChannel(new SentryLog({ client: Sentry }));
+```
+
+### Let the channel initialize Sentry (new apps)
+
+Pass `options`; the channel lazily imports `@sentry/node` and calls `Sentry.init` once — guarded so it never clobbers an existing client:
+
+```ts
+import { log, SentryLog } from "@warlock.js/logger";
+
+log.addChannel(
+  new SentryLog({
+    options: {
+      dsn: process.env.SENTRY_DSN,
+      environment: process.env.NODE_ENV,
+      release: process.env.GIT_SHA,
+    },
+  }),
+);
+```
+
+With neither `client` nor `options`, the channel reuses whatever global Sentry client the host already initialized.
+
+## How levels map to Sentry
+
+This is the quota-control decision. Only `eventLevels` create Sentry **events** (which consume your error quota); every other level becomes a **breadcrumb** that rides along with the next event for free.
+
+| Logger level | Default | Sentry call |
+|---|---|---|
+| `fatal` | event | `captureException` for an `Error` message, else `captureMessage(…, "fatal")` |
+| `error` | event | `captureException` for an `Error` message, else `captureMessage(…, "error")` |
+| `warn` | event | `captureMessage(…, "warning")` |
+| `success` | breadcrumb | `addBreadcrumb({ level: "info" })` |
+| `info` | breadcrumb | `addBreadcrumb({ level: "info" })` |
+| `debug` | breadcrumb | `addBreadcrumb({ level: "debug" })` |
+
+- **Errors keep their stack.** A `message` that is an `Error` goes through `captureException`, so Sentry parses the real stack and groups correctly — never pre-stringify the error.
+- **`module` / `action` become tags** and the entry's `context` becomes a structured Sentry context, both scoped to that single event via `withScope`.
+- **`success` has no Sentry severity** — it's reported as `info`.
+
+### Tuning what becomes an event
+
+```ts
+// Only errors create events; warnings drop to breadcrumbs.
+new SentryLog({ client: Sentry, eventLevels: ["error"] });
+
+// Errors + warnings + an info stream as events (noisier, more quota).
+new SentryLog({ client: Sentry, eventLevels: ["error", "warn", "info"] });
+```
+
+`levels` and `filter` from `BasicLogConfigurations` apply first — a channel-level `levels: ["error", "warn"]` drops everything else before it reaches Sentry at all.
+
+## Draining on shutdown
+
+Sentry sends events asynchronously over the network, so a synchronous flush can't wait on them. `SentryLog.flush()` calls `Sentry.flush(timeout)`; drain it on your graceful-shutdown path:
+
+```ts
+async function shutdown() {
+  await httpServer.close();
+  await log.flush();   // SentryLog.flush() → Sentry.flush(flushTimeout)
+  process.exit(0);
+}
+
+process.once("SIGTERM", shutdown);
+```
+
+`flushTimeout` (default `2000` ms) bounds the wait so an unreachable Sentry can't hang shutdown. `autoFlushOn` uses the **synchronous** `flushSync()`, which does *not* drain Sentry — wire `await log.flush()` yourself. See [`flush-logs-on-shutdown`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
+
+## If `@sentry/node` isn't installed
+
+The channel never crashes your app: the dynamic import failure is swallowed, the install instructions are written to stderr **once**, and entries are dropped silently thereafter. So registering `SentryLog` in shared config is safe even in an environment where Sentry isn't installed.
+
+## Config reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `client` | Sentry namespace / forwarder | — | Reuse an already-initialized Sentry instance. |
+| `options` | `SentryInitOptions` | — | Sentry init options (mirrors `@sentry/node`'s `NodeOptions`) — used when the channel owns Sentry. |
+| `eventLevels` | `LogLevel[]` | `["fatal", "error", "warn"]` | Levels sent as events; the rest become breadcrumbs. |
+| `flushTimeout` | `number` | `2000` | Ms `flush()` waits for the transport to drain. |
+| `levels`, `filter`, `dateFormat`, `redact` | — | — | Inherited from `BasicLogConfigurations`. |
+
+## Don't do
+
+- **Don't double-init Sentry.** Pass *either* `client` *or* `options`, not both. The channel guards against double-init, but a single owner of `Sentry.init` is cleaner.
+- **Don't send every level as an event.** `eventLevels` with `info`/`debug`/`success` will flood your Sentry quota — keep them as breadcrumbs.
+- **Don't rely on `autoFlushOn` for Sentry.** It's synchronous; a network channel needs `await log.flush()`.
+
+## See also
+
+- [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md) — `await log.flush()` on shutdown
+- [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md) — the console / file channels
+- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — build your own sink
+
+
+## test-logging-code  `@warlock.js/logger/test-logging-code/SKILL.md`
+
+---
+name: test-logging-code
+description: 'Test code that touches the logger — silence globally via log.setChannels([]) in setupFiles, assert specific log lines via a capturing LogChannel subclass (prefer it over vi.spyOn — it asserts on delivered entries, not just method calls, and isolates the shared singleton cleanly). Triggers: `log.setChannels`, `LogChannel`, `LoggingData`, `Logger`, `log.channels`; "silence logger in vitest", "assert a log line was emitted", "capture log output in tests", "test code that logs"; typical import `import { log, Logger, LogChannel, type LoggingData } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `vi.spyOn(console)`, `jest.spyOn`.'
+---
+
+# Testing — code that logs, and asserting on log output
+
+Two scenarios: **silencing the logger during tests** (most common) and **asserting that a specific log line was emitted**.
+
+## Silence the logger during tests
+
+Clear every channel once, globally. No output, no file handles, no noise.
+
+```ts title="src/setupTests.ts"
+import { log } from "@warlock.js/logger";
+
+log.setChannels([]);
+```
+
+Wire it in Vitest:
+
+```ts title="vitest.config.ts"
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    setupFiles: ["src/setupTests.ts"],
+  },
+});
+```
+
+## Assert on log output — use a capturing channel
+
+Don't spy on `console.log` and don't mock `log.info` — assert on what a channel actually received instead (see "Why not spy on `log.info`?" below). The cleanest pattern is a tiny channel that records what it sees:
+
+```ts
+import { LogChannel } from "@warlock.js/logger";
+import type { LoggingData } from "@warlock.js/logger";
+
+class CapturingChannel extends LogChannel {
+  public name = "capture";
+  public terminal = false;
+  public received: LoggingData[] = [];
+  public log(data: LoggingData) { this.received.push({ ...data }); }
+}
+```
+
+### Test against the singleton
+
+```ts
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { log } from "@warlock.js/logger";
+import { createUser } from "./users";
+
+describe("createUser", () => {
+  let capture: CapturingChannel;
+  let originalChannels: typeof log.channels;
+
+  beforeEach(() => {
+    capture = new CapturingChannel();
+    originalChannels = log.channels;
+    log.channels = [capture];
+  });
+
+  afterEach(() => {
+    log.channels = originalChannels;
+  });
+
+  it("logs a success entry when the user is created", async () => {
+    await createUser({ email: "a@b.com" });
+
+    expect(capture.received).toContainEqual(
+      expect.objectContaining({
+        type: "success",
+        module: "users",
+        action: "create",
+      }),
+    );
+  });
+});
+```
+
+### Test an isolated logger (avoid touching the singleton)
+
+If the code under test accepts a logger via injection, create one per test:
+
+```ts
+import { Logger } from "@warlock.js/logger";
+
+const testLogger = new Logger();
+const capture = new CapturingChannel();
+testLogger.addChannel(capture);
+
+await createUser({ email: "a@b.com" }, testLogger);
+
+expect(capture.received[0]!.type).toBe("success");
+```
+
+No cleanup needed — the local `Logger` is garbage-collected.
+
+## Why not spy on `log.info`?
+
+`log` is a plain `Logger` instance (`export const log = new Logger()`) and every level method lives on the prototype, so `vi.spyOn(log, "info")` *does* technically work. Prefer the capturing channel anyway:
+
+- A spy on `log.info` proves the method was **called**, not that an entry was **delivered** — it skips the whole pipeline (`minLevel` floor, redaction, per-channel `levels` / `filter`). A capturing channel asserts on the entry your code under test actually produced after all of that ran.
+- The `log` singleton is shared global state. A spy you forget to `mockRestore()` leaks into the next test; swapping `log.channels` and restoring it in `afterEach` is the same amount of code and isolates cleanly.
+- Code that logs through `log.error(...)` and the bare object form `log.log({ type, ... })` both land in channels, but only the level shortcut goes through `log.info` — a channel catches both.
+
+So capture through a channel as shown above; reach for a method spy only when you specifically want to assert "this exact shortcut was invoked".
+
+## Testing a custom channel
+
+Write specs against the channel directly; don't route through `Logger`:
+
+```ts
+import { describe, it, expect, vi } from "vitest";
+import { SlackLog } from "./slack-log";
+
+describe("SlackLog", () => {
+  it("skips non-error levels", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response());
+
+    const channel = new SlackLog({ webhookUrl: "https://test", levels: ["error"] });
+    await channel.log({ type: "info", module: "x", action: "y", message: "z" });
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+```
+
+## Testing `FileLog` and `JSONFileLog`
+
+Use real temp directories — it's the only way to exercise file IO, rotation, chunking, and JSON I/O with fidelity:
+
+```ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { randomUUID } from "node:crypto";
+
+function tempDir() {
+  const dir = path.join(os.tmpdir(), "logger-test", randomUUID());
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+```
+
+Clean up in `afterEach(() => fs.rmSync(dir, { recursive: true, force: true }))`.
+
+## Waiting for async init
+
+`LogChannel.init()` runs inside a `setTimeout(0)`. Before asserting on post-init behavior, yield once:
+
+```ts
+const channel = new FileLog({ storagePath: tempDir() });
+await new Promise((r) => setTimeout(r, 10));
+// Now `channel.isInitialized` is true and it's safe to call `channel.log(...)` for real I/O.
+```
+
+## Testing `captureAnyUnhandledRejection`
+
+Don't actually throw unhandled rejections in tests — emit the listener directly:
+
+```ts
+captureAnyUnhandledRejection();
+process.emit("unhandledRejection", new Error("test"), Promise.resolve());
+```
+
+The `uncaughtException` path additionally calls `process.exit(1)`, so stub it (or pass `{ exitOnUncaughtException: false }`) before emitting — otherwise the emitted exception tears the test runner down:
+
+```ts
+vi.spyOn(process, "exit").mockImplementation(() => undefined as never);
+captureAnyUnhandledRejection();
+process.emit("uncaughtException", new Error("test"), "uncaughtException");
+```
+
+See [`@warlock.js/logger/capture-unhandled-errors/SKILL.md`](@warlock.js/logger/capture-unhandled-errors/SKILL.md) for a full example.
+
+
+## use-log-helpers  `@warlock.js/logger/use-log-helpers/SKILL.md`
+
+---
+name: use-log-helpers
+description: 'Two DX shortcuts on every Logger — log.assert(condition, module, action, message, context?) logs an error when condition is falsy (free on the happy path), log.timer(module, action) returns an end-function emitting an info entry with measured duration. Triggers: `log.assert`, `log.timer`, `durationMs`; "assert an invariant via logger", "measure how long an operation took", "time a request", "log operation duration"; typical import `import { log } from "@warlock.js/logger"`. Skip: basics — `@warlock.js/logger/logger-basics/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.'
+---
+
+# Helpers — `assert`, `timer`
+
+Two small DX shortcuts on every `Logger` (and the bound `log` helper). They route through the normal log pipeline — every channel sees what they emit.
+
+## `log.assert(condition, module, action, message, context?)`
+
+Logs an `error` entry when `condition` is falsy. Genuinely free in the happy path: when the condition is truthy, the entry is never built and channels are never invoked.
+
+```ts
+log.assert(user !== null, "auth", "session", "user vanished mid-flight", {
+  sessionId,
+});
+
+// truthy → no log call
+// falsy  → equivalent to log.error("auth", "session", "user vanished...", { sessionId })
+```
+
+The level is implicitly `error` — assertions express failures, not warnings. If you need a non-error level, use `log.error` / `log.warn` directly with your own `if`.
+
+### Why not `console.assert`?
+
+`console.assert` writes to stderr only and bypasses your file/JSON channels. `log.assert` runs through the logger pipeline, so a failed assertion is captured by every persistent channel you've configured. See [`@warlock.js/logger/pick-log-channel/SKILL.md`](@warlock.js/logger/pick-log-channel/SKILL.md).
+
+## `log.timer(module, action)`
+
+Returns an end-function. Calling it emits an `info` entry with `completed in <ms>ms` and a `durationMs` field in `context`.
+
+```ts
+const end = log.timer("db", "users.findById");
+const user = await usersRepo.findById(id);
+end({ id, found: !!user });
+// ℹ info [db] [users.findById] completed in 12ms
+//   ↳ { durationMs: 12, id: "abc", found: true } (when ConsoleLog has showContext: true)
+```
+
+Common patterns:
+
+```ts
+// Around an HTTP handler
+async function handle(req) {
+  const end = log.timer("http", `${req.method} ${req.url}`);
+  try {
+    return await runHandler(req);
+  } finally {
+    end({ status: res.statusCode });
+  }
+}
+
+// Around a job
+const end = log.timer("jobs", "nightly-report");
+await report.run();
+end({ rowsProcessed: report.rowCount });
+```
+
+`end()` can be called more than once if you want intermediate checkpoints — each call emits a fresh entry with the duration measured from the original `timer()` call.
+
+### Caveats
+
+- The duration is `Date.now()` based — millisecond resolution. For sub-millisecond profiling, reach for `performance.now()` directly.
+- The end-function captures `this` at construction; calling it after the logger is reconfigured still routes through the same `Logger` instance.
+- `log.timer` shorthand binds to the singleton — see [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md) for how to swap channels per test.
+
+
+## write-custom-log-channel  `@warlock.js/logger/write-custom-log-channel/SKILL.md`
+
+---
+name: write-custom-log-channel
+description: 'Extend the abstract LogChannel class for custom sinks — Slack, database, HTTP endpoint, in-memory buffer. Triggers: `LogChannel`, `LogContract`, `LoggingData`, `shouldBeLogged`, `init`, `flush`, `flushSync`, `terminal`; "log to slack", "log to a database", "send logs to datadog / loki HTTP api", "in-memory test capture channel", "build a custom log sink"; typical import `import { LogChannel, type LoggingData, type LogContract } from "@warlock.js/logger"`. Skip: built-in channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing libs `winston-transport`, `pino-transport`.'
+---
+
+# Custom channels — extending `LogChannel`
+
+Build a sink for any destination — Slack, a database, an HTTP endpoint — by extending the abstract `LogChannel` class.
+
+## The 5-line minimum
+
+```ts
+import { LogChannel, type LoggingData } from "@warlock.js/logger";
+
+export class NullChannel extends LogChannel {
+  public name = "null";
+  public log(_data: LoggingData) {}
+}
+```
+
+Then:
+```ts
+log.addChannel(new NullChannel());
+```
+
+That's a working channel. `LogChannel` provides the scaffolding; you only need to supply `name` and `log()`.
+
+## What `LogChannel` gives you
+
+| Thing | Who provides it |
+|---|---|
+| `name`, `description`, `terminal` | You (fields on your subclass) |
+| `log(data)` | **You must implement** — abstract |
+| `flushSync()` | You (optional sync drain — only if you buffer) |
+| `flush()` | You (optional async drain — only if you buffer over async I/O) |
+| `init()` | You (optional async hook — see below) |
+| `shouldBeLogged(data)` | `LogChannel` — combines `levels` + `filter` |
+| `config<K>(key)` | `LogChannel` — merges user config with `defaultConfigurations` |
+| `getDateAndTimeFormat()` | `LogChannel` — returns resolved `dateFormat` |
+
+## Complete example — SlackLog
+
+```ts title="src/channels/slack-log.ts"
+import { LogChannel, type BasicLogConfigurations, type LoggingData } from "@warlock.js/logger";
+
+// `LogChannel<Options>` constrains `Options extends BasicLogConfigurations`,
+// so extend the base to keep the inherited levels / filter / redact options.
+type SlackConfig = BasicLogConfigurations & {
+  webhookUrl: string;
+};
+
+export class SlackLog extends LogChannel<SlackConfig> {
+  public name = "slack";
+  public description = "Posts errors + warnings to a Slack webhook";
+
+  public async log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;   // ← inherit levels + filter
+
+    await fetch(this.config("webhookUrl"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `[${data.type.toUpperCase()}] [${data.module}][${data.action}]: ${data.message}`,
+      }),
+    });
+  }
+}
+```
+
+Register it alongside built-ins:
+
+```ts
+log.setChannels([
+  new ConsoleLog(),
+  new FileLog({ chunk: "daily" }),
+  new SlackLog({
+    webhookUrl: process.env.SLACK_WEBHOOK_URL!,
+    levels: ["error", "warn"],
+  }),
+]);
+```
+
+## The `init()` hook
+
+Override `protected async init()` for one-time setup — open a socket, connect to a DB, prepare a write stream. Runs automatically after construction (inside a `setTimeout(0)`); `isInitialized` flips to `true` once resolved.
+
+```ts
+export class DatabaseLog extends LogChannel<
+  BasicLogConfigurations & { connectionString: string }
+> {
+  public name = "database";
+  private client!: SomeDbClient;
+
+  protected async init() {
+    this.client = await SomeDbClient.connect(this.config("connectionString"));
+  }
+
+  public async log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    await this.client.insert("logs", data);
+  }
+}
+```
+
+## Implementing `flushSync()`
+
+Only if your channel buffers. Signature: `flushSync?(): void`. Synchronous — no `await`, no promises.
+
+```ts
+export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: string }> {
+  public name = "batch-http";
+  private buffer: LoggingData[] = [];
+
+  public log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    this.buffer.push(data);
+    if (this.buffer.length >= 100) void this.drain();
+  }
+
+  public flushSync() {
+    // Synchronous HTTP — use `node:http` or `XMLHttpRequest` polyfill.
+    // If sync HTTP isn't possible, at least dump the buffer to disk here
+    // so a follow-up async drain can recover it next boot.
+  }
+
+  private async drain() { /* async post to this.config("url") */ }
+}
+```
+
+## Implementing `flush()` — async drain
+
+`flushSync()` is synchronous, so a channel that delivers over the network (or any async I/O) can't drain that way. Implement `flush(): Promise<void>` so `await log.flush()` drains it on a graceful shutdown:
+
+```ts
+export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: string }> {
+  public name = "batch-http";
+  private buffer: LoggingData[] = [];
+
+  public log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    this.buffer.push(data);
+    if (this.buffer.length >= 100) void this.drain();
+  }
+
+  public async flush() {
+    await this.drain();   // awaited by log.flush() on shutdown
+  }
+
+  private async drain() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0);
+    await fetch(this.config("url"), { method: "POST", body: JSON.stringify(batch) });
+  }
+}
+```
+
+`Logger.flush()` isolates each channel — a rejecting `flush()` won't break the others — but handle your own failures so a shutdown drain doesn't silently drop the batch. Implement `flushSync()` too (e.g. dump to disk) when you also want a best-effort sync path for `autoFlushOn`.
+
+## The `terminal` property
+
+- `terminal = true` (ConsoleLog default) → the logger passes the **original** message, ANSI codes intact.
+- `terminal = false` (base default, all file channels) → the logger passes a shallow-cloned copy whose `message` has ANSI codes stripped.
+
+Set `terminal = true` on a channel only if its output is a TTY that should render colors.
+
+## `LogContract` — the minimal interface
+
+If you don't want anything `LogChannel` provides (level filtering, config merging), implement `LogContract` directly:
+
+```ts
+import type { LogContract, LoggingData } from "@warlock.js/logger";
+
+class MinimalSlack implements LogContract {
+  public name = "slack";
+
+  public async log(data: LoggingData) {
+    if (data.type !== "error") return;
+    await fetch(process.env.SLACK_WEBHOOK!, { /* ... */ });
+  }
+}
+```
+
+Prefer extending `LogChannel` unless you have a concrete reason not to — the level/filter plumbing is worth keeping.
+
+## Don't do
 
----
-name: write-custom-log-channel
-description: 'Extend the abstract LogChannel class for custom sinks — Slack, database, HTTP endpoint, in-memory buffer. Triggers: `LogChannel`, `LogContract`, `LoggingData`, `shouldBeLogged`, `init`, `flush`, `flushSync`, `terminal`; "log to slack", "log to a database", "send logs to datadog / loki HTTP api", "in-memory test capture channel", "build a custom log sink"; typical import `import { LogChannel, type LoggingData, type LogContract } from "@warlock.js/logger"`. Skip: built-in channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing libs `winston-transport`, `pino-transport`.'
----
-
-# Custom channels — extending `LogChannel`
-
-Build a sink for any destination — Slack, a database, an HTTP endpoint — by extending the abstract `LogChannel` class.
-
-## The 5-line minimum
-
-```ts
-import { LogChannel, type LoggingData } from "@warlock.js/logger";
-
-export class NullChannel extends LogChannel {
-  public name = "null";
-  public log(_data: LoggingData) {}
-}
-```
-
-Then:
-```ts
-log.addChannel(new NullChannel());
-```
-
-That's a working channel. `LogChannel` provides the scaffolding; you only need to supply `name` and `log()`.
-
-## What `LogChannel` gives you
-
-| Thing | Who provides it |
-|---|---|
-| `name`, `description`, `terminal` | You (fields on your subclass) |
-| `log(data)` | **You must implement** — abstract |
-| `flushSync()` | You (optional sync drain — only if you buffer) |
-| `flush()` | You (optional async drain — only if you buffer over async I/O) |
-| `init()` | You (optional async hook — see below) |
-| `shouldBeLogged(data)` | `LogChannel` — combines `levels` + `filter` |
-| `config<K>(key)` | `LogChannel` — merges user config with `defaultConfigurations` |
-| `getDateAndTimeFormat()` | `LogChannel` — returns resolved `dateFormat` |
-
-## Complete example — SlackLog
-
-```ts title="src/channels/slack-log.ts"
-import { LogChannel, type BasicLogConfigurations, type LoggingData } from "@warlock.js/logger";
-
-// `LogChannel<Options>` constrains `Options extends BasicLogConfigurations`,
-// so extend the base to keep the inherited levels / filter / redact options.
-type SlackConfig = BasicLogConfigurations & {
-  webhookUrl: string;
-};
-
-export class SlackLog extends LogChannel<SlackConfig> {
-  public name = "slack";
-  public description = "Posts errors + warnings to a Slack webhook";
-
-  public async log(data: LoggingData) {
-    if (!this.shouldBeLogged(data)) return;   // ← inherit levels + filter
-
-    await fetch(this.config("webhookUrl"), {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        text: `[${data.type.toUpperCase()}] [${data.module}][${data.action}]: ${data.message}`,
-      }),
-    });
-  }
-}
-```
-
-Register it alongside built-ins:
-
-```ts
-log.setChannels([
-  new ConsoleLog(),
-  new FileLog({ chunk: "daily" }),
-  new SlackLog({
-    webhookUrl: process.env.SLACK_WEBHOOK_URL!,
-    levels: ["error", "warn"],
-  }),
-]);
-```
-
-## The `init()` hook
-
-Override `protected async init()` for one-time setup — open a socket, connect to a DB, prepare a write stream. Runs automatically after construction (inside a `setTimeout(0)`); `isInitialized` flips to `true` once resolved.
-
-```ts
-export class DatabaseLog extends LogChannel<
-  BasicLogConfigurations & { connectionString: string }
-> {
-  public name = "database";
-  private client!: SomeDbClient;
-
-  protected async init() {
-    this.client = await SomeDbClient.connect(this.config("connectionString"));
-  }
-
-  public async log(data: LoggingData) {
-    if (!this.shouldBeLogged(data)) return;
-    await this.client.insert("logs", data);
-  }
-}
-```
-
-## Implementing `flushSync()`
-
-Only if your channel buffers. Signature: `flushSync?(): void`. Synchronous — no `await`, no promises.
-
-```ts
-export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: string }> {
-  public name = "batch-http";
-  private buffer: LoggingData[] = [];
-
-  public log(data: LoggingData) {
-    if (!this.shouldBeLogged(data)) return;
-    this.buffer.push(data);
-    if (this.buffer.length >= 100) void this.drain();
-  }
-
-  public flushSync() {
-    // Synchronous HTTP — use `node:http` or `XMLHttpRequest` polyfill.
-    // If sync HTTP isn't possible, at least dump the buffer to disk here
-    // so a follow-up async drain can recover it next boot.
-  }
-
-  private async drain() { /* async post to this.config("url") */ }
-}
-```
-
-## Implementing `flush()` — async drain
-
-`flushSync()` is synchronous, so a channel that delivers over the network (or any async I/O) can't drain that way. Implement `flush(): Promise<void>` so `await log.flush()` drains it on a graceful shutdown:
-
-```ts
-export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: string }> {
-  public name = "batch-http";
-  private buffer: LoggingData[] = [];
-
-  public log(data: LoggingData) {
-    if (!this.shouldBeLogged(data)) return;
-    this.buffer.push(data);
-    if (this.buffer.length >= 100) void this.drain();
-  }
-
-  public async flush() {
-    await this.drain();   // awaited by log.flush() on shutdown
-  }
-
-  private async drain() {
-    if (this.buffer.length === 0) return;
-    const batch = this.buffer.splice(0);
-    await fetch(this.config("url"), { method: "POST", body: JSON.stringify(batch) });
-  }
-}
-```
-
-`Logger.flush()` isolates each channel — a rejecting `flush()` won't break the others — but handle your own failures so a shutdown drain doesn't silently drop the batch. Implement `flushSync()` too (e.g. dump to disk) when you also want a best-effort sync path for `autoFlushOn`.
-
-## The `terminal` property
-
-- `terminal = true` (ConsoleLog default) → the logger passes the **original** message, ANSI codes intact.
-- `terminal = false` (base default, all file channels) → the logger passes a shallow-cloned copy whose `message` has ANSI codes stripped.
-
-Set `terminal = true` on a channel only if its output is a TTY that should render colors.
-
-## `LogContract` — the minimal interface
-
-If you don't want anything `LogChannel` provides (level filtering, config merging), implement `LogContract` directly:
-
-```ts
-import type { LogContract, LoggingData } from "@warlock.js/logger";
-
-class MinimalSlack implements LogContract {
-  public name = "slack";
-
-  public async log(data: LoggingData) {
-    if (data.type !== "error") return;
-    await fetch(process.env.SLACK_WEBHOOK!, { /* ... */ });
-  }
-}
-```
-
-Prefer extending `LogChannel` unless you have a concrete reason not to — the level/filter plumbing is worth keeping.
-
-## Don't do
-
-- Don't mutate `data` inside `log()`. Later channels see the mutation if the logger passes the same reference.
-- Don't throw synchronously from `log()`. The logger fires it without awaiting; an unhandled rejection takes down the process (unless `captureAnyUnhandledRejection` is wired up — and then it's embarrassing to be the cause).
-- Don't block the event loop. `log()` may be sync or async; if your work takes >100ms, make it async and return the promise.
-- Don't forget `shouldBeLogged(data)` at the top of `log()` — or your channel silently ignores `levels` / `filter` config.
+- Don't mutate `data` inside `log()`. Later channels see the mutation if the logger passes the same reference.
+- Don't throw synchronously from `log()`. The logger fires it without awaiting; an unhandled rejection takes down the process (unless `captureAnyUnhandledRejection` is wired up — and then it's embarrassing to be the cause).
+- Don't block the event loop. `log()` may be sync or async; if your work takes >100ms, make it async and return the promise.
+- Don't forget `shouldBeLogged(data)` at the top of `log()` — or your channel silently ignores `levels` / `filter` config.