@warlock.js/logger 5.19.0 → 5.20.0

package/llms.txt

@@ -7,14 +7,14 @@
 ## Skills
 
 - [capture-unhandled-errors](@warlock.js/logger/capture-unhandled-errors/SKILL.md): (no description)
-- [configure-logger](@warlock.js/logger/configure-logger/SKILL.md): Setup — registering channels at startup in @warlock.js/logger; use when you need to configure logger.
+- [configure-logger](@warlock.js/logger/configure-logger/SKILL.md): (no description)
 - [filter-log-entries](@warlock.js/logger/filter-log-entries/SKILL.md): (no description)
 - [flush-logs-on-shutdown](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md): (no description)
 - [logger-basics](@warlock.js/logger/logger-basics/SKILL.md): Start here for @warlock.js/logger channels, structured entries, transports, and application logging setup.
 - [overview](@warlock.js/logger/overview/SKILL.md): (no description)
 - [pick-log-channel](@warlock.js/logger/pick-log-channel/SKILL.md): (no description)
-- [redact-sensitive-log-fields](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md): Redaction — keeping secrets out of logs in @warlock.js/logger; use when you need to redact sensitive log fields.
+- [redact-sensitive-log-fields](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md): (no description)
 - [ship-logs-to-sentry](@warlock.js/logger/ship-logs-to-sentry/SKILL.md): (no description)
-- [test-logging-code](@warlock.js/logger/test-logging-code/SKILL.md): Testing — code that logs, and asserting on log output in @warlock.js/logger; use when you need to test logging code.
-- [use-log-helpers](@warlock.js/logger/use-log-helpers/SKILL.md): Helpers — assert, timer in @warlock.js/logger; use when you need to use log helpers.
+- [test-logging-code](@warlock.js/logger/test-logging-code/SKILL.md): (no description)
+- [use-log-helpers](@warlock.js/logger/use-log-helpers/SKILL.md): (no description)
 - [write-custom-log-channel](@warlock.js/logger/write-custom-log-channel/SKILL.md): (no description)

package/package.json

@@ -3,8 +3,8 @@
   "description": "A powerful logging system  for messages and errors in nodejs.",
   "dependencies": {
     "@mongez/copper": "^2.1.2",
-    "@mongez/reinforcements": "^4.0.1",
-    "@warlock.js/fs": "5.19.0",
+    "@mongez/reinforcements": "^4.0.2",
+    "@warlock.js/fs": "5.20.0",
     "dayjs": "^1.11.9",
     "safe-stable-stringify": "^2.5.0"
   },
@@ -32,7 +32,7 @@
   "warlock": {
     "environment": "server"
   },
-  "version": "5.19.0",
+  "version": "5.20.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

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

@@ -1,6 +1,6 @@
 ---
 name: capture-unhandled-errors
-description: "Error capture — routing Node's unhandled errors through the logger in @warlock.js/logger; use when you need to 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

package/skills/configure-logger/SKILL.md

@@ -1,105 +1,105 @@
----
-name: configure-logger
-description: "Setup — registering channels at startup in @warlock.js/logger; use when you need to configure logger."
----
-
-# 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

package/skills/filter-log-entries/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: filter-log-entries
-description: "Filtering — levels + filter predicate + minLevel in @warlock.js/logger; use when you need to 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`

package/skills/flush-logs-on-shutdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flush-logs-on-shutdown
-description: "Lifecycle — flushing buffered channels before exit in @warlock.js/logger; use when you need to 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

package/skills/index.md

@@ -0,0 +1,20 @@
+---
+description: "Structured logging for Warlock.js with pluggable channels, redaction and shutdown flushing. Exports `log`, `Logger`, `LogChannel`, `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `applyRedact`, `DEFAULT_REDACT_KEYS`, `captureAnyUnhandledRejection`. Use for: \"log an error with context\", \"write logs to a file as JSON\", \"send errors to Sentry\", \"hide passwords and tokens in logs\", \"flush logs before exit\", \"catch unhandled rejections\", \"write my own log channel\". Not this package: HTTP request handling and error responses live in @warlock.js/core; scheduled jobs are @warlock.js/scheduler."
+---
+# @warlock.js/logger
+
+The `log` singleton (a `Logger`) sends each entry, with module, action, level and message, to every configured `LogChannel`. Channels decide where entries go (console, file, JSON file, Sentry, custom) and can filter by level or module.
+
+## The 80% path
+1. Orient: `overview.md`, `logger-basics.md`.
+2. Pick channels: `pick-log-channel.md`; set them up: `configure-logger.md`.
+3. Log via `log.info/warn/error` or helpers: `use-log-helpers.md`.
+4. Redact secrets: `redact-sensitive-log-fields.md`; narrow output: `filter-log-entries.md`.
+5. Production safety: `capture-unhandled-errors.md`, `flush-logs-on-shutdown.md`, `ship-logs-to-sentry.md`.
+6. Extend or test: `write-custom-log-channel.md`, `test-logging-code.md`.
+
+## Conventions and pitfalls
+- `fatal` does not flush or exit by itself; the caller awaits `log.flush()` and then exits.
+- File channels buffer, so an unflushed process exit loses the tail of the log.
+- Configure redaction before logging request bodies or auth data; the default key set is a floor, not a guarantee.
+- Log structured context objects rather than interpolated strings, so channels and Sentry can index them.

package/skills/pick-log-channel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pick-log-channel
-description: "Channels — which one to pick and how to configure it in @warlock.js/logger; use when you need to choose 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

package/skills/redact-sensitive-log-fields/SKILL.md

@@ -1,156 +1,156 @@
----
-name: redact-sensitive-log-fields
-description: "Redaction — keeping secrets out of logs in @warlock.js/logger; use when you need to redact sensitive log fields."
----
-
-# 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.
+---
+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.