docs: describe the boot check by what it checks, not by what readers do

Two rounds in a row went to claims about whether a given reader warns when
it rejects a value, and both were wrong somewhere. It varies per reader and
per branch inside one reader: compileHeaderRules warns only when Headers.set
rejects a key, and drops a typo'd `source`, a bad URLPattern, and a
non-object entry in silence; readAllowedOrigins filters bad entries with no
warning at all; compileRedirectRules warns on every branch but one.

So the docs stop asserting it. Each surface now states what the validator
checks and what it does not, and leaves downstream behaviour to the reader
that owns it. The sweeping "that key-level case is the whole of the gap"
line is gone too, since it contradicted the nested-key sentence beside it.

The built-ins lead sentence claiming every malformed entry warns was
pre-existing and is corrected in passing, since this paragraph leaned on it.

Author: vivek7405

.agents/skills/webjs/references/built-ins.md

@@ -145,7 +145,7 @@ setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
 
 ## The `"webjs"` config block (package.json)
 
-All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot with a warning, never crashing the pipeline. An UNKNOWN top-level key is treated the same way (#1300): the block is validated against the published JSON Schema once per boot, in dev and in prod alike, and one aggregated warning names what was ignored. So a `"redirect"` typed for `"redirects"` now says so in the server output instead of silently leaving the feature at its default. It never fails the boot. Know what it does NOT cover, since the remaining silent case looks like the one it fixed. It reports an unknown TOP-LEVEL key, a bad `enum` value, and a wrong-typed `boolean` / `integer`, which is 9 of the 17 keys. It does not descend into a nested object, so a misspelling inside `dev` or `start` is uncaught, and it does not type-check the other 8 (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`, `start`, `doctor`), which are the free-form array, string, and object shapes where a blunt check would start refusing configs that work. Give one of those the wrong TYPE outright (`"headers": "x"`) and it passes the boot check, and the reader falls back to its default in silence. That key-level case is the whole of what goes unreported: a malformed ENTRY inside a well-shaped `headers` or `redirects` array already warns from the reader, per the sentence above, and `doctor` is not a silent drop either, per the exception below. The one exception is `doctor.gate`, which is read by the `webjs doctor` CLI rather than the server and rejects a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
+All keys are optional, and a malformed entry in a key the SERVER reads is dropped at boot rather than crashing the pipeline, some readers warning as they drop it. An UNKNOWN top-level key no longer passes in silence either (#1300): the block is validated against the published JSON Schema once per boot, in dev and in prod alike, and one aggregated warning names what was ignored. So a `"redirect"` typed for `"redirects"` now says so in the server output instead of silently leaving the feature at its default. It never fails the boot. Know its exact reach, since what it passes over looks like what it catches. It reports an unknown TOP-LEVEL key, a bad `enum` value, and a wrong-typed `boolean` / `integer`, which is 9 of the 17 keys. It does not descend into a nested object, so a misspelling inside `dev` or `start` is not reported, and it does not type-check the other 8 (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`, `start`, `doctor`), which are the free-form array, string, and object shapes where a blunt check would start refusing configs that work. Whether anything else notices a value this check passes over is up to that value's own reader, and it varies by reader. The one exception is `doctor.gate`, which is read by the `webjs doctor` CLI rather than the server and rejects a bad entry outright (see the doctor severity gate below): a gate whose typo was quietly ignored would leave CI un-gated while looking gated, which is the one thing that mechanism cannot afford.
 
 ### Security headers
 

packages/core/src/webjs-config.d.ts

@@ -18,14 +18,12 @@
  * top-level key, every bad `enum` value, and every wrong-typed `boolean` /
  * `integer` (9 of the 17 keys). It does NOT type-check the other 8
  * (`headers`, `redirects`, `basePath`, `allowedOrigins`, `csp`, `dev`,
- * `start`, `doctor`), so giving one of THOSE the wrong type outright
- * (`"headers": "x"`) passes the boot check and its reader then falls back
- * to the default without a word. Only that key-level case is unreported: a
- * malformed ENTRY inside a well-shaped `headers` / `redirects` array
- * already warns from the reader, and a bad `doctor` shape exits
- * `webjs doctor` non-zero rather than being dropped. The boot check warns
- * and never throws, so a typo costs one feature its setting rather than
- * the whole app its boot.
+ * `start`, `doctor`), whose schema types are the free-form array, string,
+ * and object shapes, and it does not descend into a nested object, so a
+ * misspelling inside `dev` or `start` is not reported either. Whether
+ * anything else notices what this check passes over is up to the
+ * individual reader. The boot check warns and never throws, so a typo
+ * costs one feature its setting rather than the whole app its boot.
  *
  * LOCKSTEP: this file, the JSON Schema at
  * packages/server/webjs-config.schema.json, and the reader functions MUST

packages/server/src/webjs-config-validate.js

@@ -49,16 +49,17 @@ import { fileURLToPath } from 'node:url';
  * unchecked are the free-form ones, where a naive check starts refusing
  * configs that work.
  *
- * What that actually leaves unreported is narrower than the list looks, and
- * worth stating precisely so nobody widens this on a wrong premise. It is the
- * KEY-level type only (`"headers": "x"`, which the reader then ignores in
- * silence). A malformed ENTRY inside a well-shaped `headers` / `redirects`
- * array already warns from the reader itself, and a wrong-shaped `doctor` is
- * not a silent drop at all: the server never reads that key, and `webjs doctor`
- * exits 1 on it (`readDoctorPolicy`).
+ * That is enough for the case this exists to close, which is a typo'd top-level
+ * key silently dropped, plus the two leaf kinds a schema can decide
+ * unambiguously.
  *
- * That is enough for the case this exists to close, which is a typo'd key
- * silently dropped, plus the two leaf kinds a schema can decide unambiguously.
+ * Describe this by what IT checks, never by what each reader does when the
+ * check stays quiet. Whether a given reader warns on a value it rejects varies
+ * per reader and per branch within one reader, so a summary of it is wrong
+ * somewhere almost immediately, and three review rounds on this PR were spent
+ * proving exactly that. `webjs.doctor` is the sharpest example: the server never
+ * reads that key at all, and `webjs doctor` exits 1 on a bad shape rather than
+ * dropping it.
  *
  * @param {Record<string, unknown>} schema the webjs-block schema
  * @param {Record<string, unknown>} value a candidate `webjs` object

website/app/docs/configuration/page.ts

@@ -162,8 +162,8 @@ webjs routes --help     # one command's help (flag form)</code-block>
     <h2>Config typos are reported at boot</h2>
     <p>Every key in the <code>webjs</code> block is optional, which means an unknown one has no way to announce itself: write <code>"redirect"</code> for <code>"redirects"</code> and the key is simply never read, the feature sits at its default, and the app looks configured. So WebJs validates the block against its published JSON Schema once per boot, in development and in production alike, and prints a single warning naming what it ignored.</p>
     <p>It is a <strong>warning, never a failure</strong>. A typo costs one feature its setting, and refusing to boot over that would cost the whole app, usually mid-deploy.</p>
-    <p><strong>What it catches, and what it does not.</strong> It reports an unknown top-level key, a value outside an allowed set (<code>trailingSlash</code>), and a wrong-typed boolean or whole number (<code>elide</code>, <code>seed</code>, <code>clientRouter</code>, <code>maxBodyBytes</code>, <code>maxMultipartBytes</code>, and the three timeouts). That is 9 of the 17 keys. It does not descend into nested objects, so a key misspelled inside <code>webjs.dev</code> or <code>webjs.start</code> is missed, and it does not check the type of the other 8 (<code>headers</code>, <code>redirects</code>, <code>basePath</code>, <code>allowedOrigins</code>, <code>csp</code>, <code>dev</code>, <code>start</code>, <code>doctor</code>), which are the free-form array, string, and object shapes where a blunt check would start rejecting configs that work. Give one of those the wrong type outright, as in <code>"headers": "x"</code>, and it passes this check and its reader quietly falls back to the default.</p>
-    <p>That key-level case is the whole of the gap. A malformed <em>entry</em> inside a well-shaped <code>headers</code> or <code>redirects</code> array already warns on its own, and a wrong-shaped <code>doctor</code> block is not dropped at all: <code>webjs doctor</code> exits non-zero naming it, because a silently ignored gate would leave CI un-gated while looking gated. Editors catch more of this earlier still: a scaffolded app wires the schema into <code>.vscode/settings.json</code>, and the <code>WebjsConfig</code> type from <code>@webjsdev/core</code> types the block while you author it.</p>
+    <p><strong>What it catches, and what it does not.</strong> It reports an unknown top-level key, a value outside an allowed set (<code>trailingSlash</code>), and a wrong-typed boolean or whole number (<code>elide</code>, <code>seed</code>, <code>clientRouter</code>, <code>maxBodyBytes</code>, <code>maxMultipartBytes</code>, and the three timeouts). That is 9 of the 17 keys. It does not descend into nested objects, so a key misspelled inside <code>webjs.dev</code> or <code>webjs.start</code> is missed, and it does not check the type of the other 8 (<code>headers</code>, <code>redirects</code>, <code>basePath</code>, <code>allowedOrigins</code>, <code>csp</code>, <code>dev</code>, <code>start</code>, <code>doctor</code>), which are the free-form array, string, and object shapes where a blunt check would start rejecting configs that work. Give one of those the wrong type outright, as in <code>"headers": "x"</code>, and it passes this check. Whether anything downstream then says so is up to that key's own reader.</p>
+    <p>Editors catch more of this earlier still: a scaffolded app wires the schema into <code>.vscode/settings.json</code>, and the <code>WebjsConfig</code> type from <code>@webjsdev/core</code> types the block while you author it. The one part of the block that is never merely dropped is <code>webjs.doctor</code>, which the server does not read at all and which <code>webjs doctor</code> exits non-zero on when it is malformed, because a silently ignored gate would leave CI un-gated while looking gated.</p>
 
     <h2>Environment Variables</h2>
     <p>Use <code>process.env</code> in server-side code (pages, actions, route handlers, middleware). WebJs auto-loads <code>&lt;appDir&gt;/.env</code> into <code>process.env</code> once at boot using Node 24+'s built-in <code>process.loadEnvFile</code>, so a scaffolded app with a committed <code>.env.example</code> and a developer-copied <code>.env</code> just works without installing <code>dotenv</code> or wiring up the file path. The auto-load fires before any server-only module is imported, which matters for code that reads <code>process.env</code> at module-init time (e.g. <code>createAuth({ secret: process.env.AUTH_SECRET })</code>).</p>