jskelet 0.5.5 → 0.6.1

package/docs/en/05-islands.md

@@ -123,25 +123,30 @@ will still mount.
 ```
 client/
 ├── entries/
-│   ├── main.js       the shared bootstrap loaded on every page
+│   ├── main.js       shared bootstrap on every page (or main.ts)
 │   └── chart.js      only on the pages that ask for it
 └── islands/
-    ├── counter.js
+    ├── counter.ts    .js or .ts
     └── chart.js
 ```
 
-**Every file** under `client/entries/*.js` **is an esbuild entry**. `main.js`
-is loaded by the layout on every page (if it is in the manifest). Extra entries
-are loaded only on the pages that ask for them:
+**Every file** under `client/entries/*.{js,ts,mts}` **is an esbuild entry**.
+`main.js` (or `main.ts`) is loaded by the layout on every page (if it is in the
+manifest). Extra entries are loaded only on the pages that ask for them. Two
+extensions for the same stem (`main.js` + `main.ts`) fail the build.
 
 ```js
-// controller
+// controller — the manifest key is always *.js
 return { view: "pages/markets", entries: ["chart.js"] };
 ```
 
 The layout resolves every name in the `entries` array with `asset(entry)` and
-emits a `<script type="module">`. The name is the manifest key, that is, the
-file name itself (`chart.js`), not its hashed form.
+emits a `<script type="module">`. The name is the manifest key (`chart.js`);
+even when the source is `chart.ts`, the unhashed key stays `.js`.
+
+Shared `@/lib` modules imported on the server must stay **`.js`** — the Node
+runtime does not resolve `.ts`; TypeScript is compiled only on the esbuild
+client path.
 
 Code splitting (`splitting: true`) is on: modules shared by two entries end up
 in a common chunk and are not downloaded twice.

package/docs/en/06-caching.md

@@ -231,7 +231,12 @@ price is acceptable, because live fields such as prices are updated on the
 client over WebSocket.
 
 The store is an LRU: an accessed entry is moved to the end, and once the limit
-(`cache().maxEntries`, 500 by default) is exceeded the oldest is evicted.
+(`cache().maxEntries`, 500 by default) is exceeded the oldest is evicted. Config
+may ask for more than 500; it **cannot exceed 800** — a higher value is clamped
+to 800 with a warning. Separately, in-process HTML strings plus compressed
+bodies **cannot exceed 256 MB**. A fat page or a `vary.host` copy that is still
+under the count limit is evicted by this budget too. A single page larger than
+256 MB is not stored; that response is still sent.
 
 ## What gets written to the cache
 
@@ -1145,9 +1150,9 @@ export default {
       html: { "/": 60, "/news/:slug": 300 },
       prewarm: {
         onVisit: {
-          perPage: 20,      // at most this many links per page
-          concurrency: 2,   // optional
-          rps: 4,           // optional; 0 = unlimited
+          perPage: 20,      // at most this many links per page; ceiling 20
+          concurrency: 2,   // ceiling 2
+          rps: 2,           // ceiling 2; 0 is clamped to 2 as well
         },
       },
     };
@@ -1163,7 +1168,15 @@ Rules:
   degraded or `no-store` responses do not extract links.
 - The warmer's own UA (`brand.prewarmUserAgent`) does not trigger — no crawl
   loop.
-- Paths that are already fresh are not enqueued.
+- Paths that are already fresh are not enqueued. Real keys look like
+  `h=host|/path?`; the check sees the vary prefix and the trailing `?`.
+  With `vary.host`, only this request's host counts as fresh.
+- The pending queue holds at most 64 paths; links beyond that are left for a
+  later response.
+- `perPage` 20, `rps` 2 and `concurrency` 2 are ceilings. A higher value (and
+  `rps: 0`) is clamped with a warning. Warm requests stay on loopback; when
+  `vary.host` is on, the public host is sent as `x-forwarded-host`, so a second
+  `h=127.0.0.1` entry is not created.
 - `nofollow`, `target="_blank"`, `data-no-prefetch`, `prewarmSkip` and
   `navigation.exclude` share the same exemptions as Speculation Rules.
 - Query strings are not warmed (default cache policy treats query as dynamic).
@@ -1308,8 +1321,9 @@ The requests go out with the headers `user-agent: jskelet-prewarm`
 (`brand.prewarmUserAgent`) and `accept-encoding: br, gzip`; the second one so
 that the compressed body enters the cache too.
 
-If `DEV_TOKEN` is set, the warm-up carries the token as a cookie; otherwise the
-dev gate returns 404 for all pages and the cache never fills.
+If the dev gate is on, the warm-up carries the token as a cookie; otherwise the
+gate returns 404 for all pages and the cache never fills. `DEV_TOKEN` alone
+does not turn the gate on.
 
 The request list in the dev panel and the terminal filter out requests carrying
 `prewarmUserAgent`: so that hundreds of warm-up requests do not flood the view.

package/docs/en/07-configuration.md

@@ -55,7 +55,7 @@ export default {
     lang: "tr",
   },
 
-  layout: "views/layout.ejs",
+  layout: "views/layout.jsk",
   routes: ["./routes/10-pages.mjs", "./routes/99-catch-all.mjs"],
   trailingSlash: false,
 
@@ -213,27 +213,32 @@ cross-subdomain handoff bridge for a short session id.
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` or `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | When on: `POST /_jskelet/auth/handoff` + `?handoff=` redeem. Object: `allowedCookieNames` (required), `ttlSeconds?`, `path?`, `maxValueBytes?`, `maxPendingTickets?`, `maxMintsPerIpPerMinute?` |
 
 ```js
 auth: {
-  crossSubdomainHandoff: { ttlSeconds: 60 },
+  crossSubdomainHandoff: {
+    allowedCookieNames: ["sid"],
+    ttlSeconds: 60,
+  },
 },
 ```
 
-Details and the `window.name` fallback:
-[12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md).
+The mint endpoint is mounted **after** the CSRF middleware (origin checks).
+Cookie names outside the allowlist or that are not RFC 6265 tokens get 400.
+Details: [12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md).
 
 ## `layout`
 
 **Type:** `string` — **Default:** none (automatic resolution)
 
-Path of the layout `.ejs` file. The value given is resolved relative to the
-**parent directory of the views directory**, so with the default `views`,
-`"views/custom.ejs"` → `<root>/views/custom.ejs`.
+Path of the layout file (`.jsk` or legacy `.ejs`). The value given is resolved
+relative to the **parent directory of the views directory**, so with the default
+`views`, `"views/custom.jsk"` → `<root>/views/custom.jsk`.
 
-If not given, in order: `views/layout.ejs` if it exists, otherwise the
-framework's minimal layout. Details: [04-rendering.md](./04-rendering.md).
+If not given, in order: `views/layout.jsk`, `views/layout.ejs` (legacy),
+otherwise the framework's `src/templates/layout.jsk` default. Details:
+[04-rendering.md](./04-rendering.md).
 
 ## `routes`
 
@@ -293,6 +298,21 @@ static: {
 }
 ```
 
+## `devGate`
+
+**Type:** `boolean` — **Default:** `false`
+
+Hides an environment that is not public yet. **`DEV_TOKEN` alone does not lock
+the site.** A shared task definition can carry the same variable into
+production; visitors are not required to present a token, and the site stays
+open.
+
+Turn the gate on with `devGate: true` or `DEV_GATE=1`. Then a request without
+the token gets a 404. `DEV_GATE=0` also turns off a gate the config enabled.
+If the token is empty, requests still pass even when the gate is on.
+
+Details: [09-dev-tools.md](./09-dev-tools.md).
+
 ## `devGateBypass`
 
 **Type:** `string[]` — **Default:**
@@ -300,8 +320,7 @@ static: {
 
 **Exact** paths the dev gate never closes off under any circumstances (not a
 prefix, an exact match). This is so that the health check and the robots files
-stay reachable in an environment where `DEV_TOKEN` is set. If provided, it
-replaces the default.
+stay reachable while the gate is on. If provided, it replaces the default.
 
 Details: [09-dev-tools.md](./09-dev-tools.md).
 
@@ -335,7 +354,7 @@ field reference.
 | `trustProxy` | `boolean` | `true` | Express's `trust proxy` setting. Needed behind a reverse proxy for the correct protocol and client IP. |
 | `cookieSecret` | `string \| null` | `null` | The signed cookie secret. When absent, `JSKELET_SECRET` is read. |
 | `csrf.enabled` | `boolean` | `true` | The origin / `Sec-Fetch-Site` check. |
-| `csrf.token` | `boolean` | `false` | The double-submit token layer. |
+| `csrf.token` | `boolean` | `false` | The double-submit token layer. **Turn on** for cookie-session forms. |
 | `csrf.allowedOrigins` | `string[]` | `[]` | Origins accepted alongside our own host. |
 | `csrf.exclude` | `string[]` | `[]` | Paths exempt from the check; `source` pattern syntax. |
 | `csrf.cookieName` | `string` | `"csrf_token"` | Name of the token cookie. |
@@ -343,14 +362,17 @@ field reference.
 | `csrf.headerName` | `string` | `"x-csrf-token"` | Header the token is also accepted in. |
 
 `trustProxy` should be **turned off** on a server exposed directly to the
-internet: while it is on, a client can forge its own `X-Forwarded-For` and rate
-limiting or audit logs see the wrong address.
+internet: while it is on, a client can forge `X-Forwarded-For` /
+`X-Forwarded-Proto` / Host, and rate limits, admin IP allowlists, Secure
+cookies, and cache `vary.host` see the wrong address. Behind a reverse proxy
+(nginx, Caddy, Cloudflare), `true` is the right default.
 
 The CSRF check only rejects requests that are **known** to be cross-site — when
 `Origin` does not match or `Sec-Fetch-Site: cross-site` arrives. If neither is
 present the request passes, because browsers always send `Origin` on a
-cross-origin POST while webhooks never do. Even so, listing non-browser
-endpoints in `csrf.exclude` makes the intent readable.
+cross-origin POST while webhooks never do. For cookie-session dashboards,
+enable `csrf.token: true` and `csrfField()` as a second layer; put webhook
+paths in `csrf.exclude`.
 
 ## `navigation`
 
@@ -433,7 +455,8 @@ body > footer { view-transition-name: site-footer; }
 ::view-transition-new(root) { animation-duration: 180ms; }
 ```
 
-A working version lives in `examples/marketing/styles/globals.css`.
+Copy the Tailwind `@source` directives and view-transition CSS into your own
+app's `styles/globals.css`; the blocks above are a starting point.
 
 **If you use CSP**, the rules are emitted as an inline
 `<script type="speculationrules">`; your `script-src` policy needs to allow it.
@@ -555,8 +578,9 @@ When `remote.allowHosts` is set, also proxies remote images at runtime
 
 If `false` is given, neither surface runs. The build step requires `sharp` and
 never runs on a watch pass. With remote enabled, `sharp` is also needed at
-**runtime**; without it the optimizer 302-redirects to the source URL. Details:
-[08-build.md](./08-build.md).
+**runtime**; without it the optimizer 302-redirects to the source URL. Fetch
+does not auto-follow redirects: every hop is re-checked against `allowHosts`
+and private addresses. Details: [08-build.md](./08-build.md).
 
 ```js
 images: {
@@ -588,7 +612,10 @@ that is not in the list returns `undefined` instead of crashing.
 clientEnv: ["PUBLIC_WS_URL", "PUBLIC_CDN_ORIGIN"]
 ```
 
-**Do not put secrets here** — the values sit in the bundle in plain text.
+**Do not put secrets here** — the values sit in the bundle in plain text. Keys
+whose names look secret-like (`SECRET`, `PASSWORD`, `TOKEN`, `API_KEY`,
+`PRIVATE`, …) are **rejected at build time** (`PUBLIC` / `PUBLISHABLE` names
+are exempt).
 
 ## `headers()`
 
@@ -598,6 +625,7 @@ clientEnv: ["PUBLIC_WS_URL", "PUBLIC_CDN_ORIGIN"]
 Response headers by path pattern. The framework only writes long-lived cache
 headers for static files; every other header (CSP, COOP, HSTS,
 X-Frame-Options…) comes from here and takes precedence over the defaults.
+Production sites should at least define the security headers below.
 
 **All** matching rules are applied (unlike redirects, it does not stop at the
 first match), in order; if two rules write the same header, the later one wins.
@@ -612,11 +640,18 @@ async headers() {
       source: "/:path*",
       headers: [
         { key: "X-Frame-Options", value: "SAMEORIGIN" },
+        { key: "X-Content-Type-Options", value: "nosniff" },
         { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+        {
+          key: "Permissions-Policy",
+          value: "camera=(), microphone=(), geolocation=()",
+        },
         {
           key: "Content-Security-Policy",
-          value: "default-src 'self'; img-src 'self' https://cdn.example.com data:",
+          value: "default-src 'self'; img-src 'self' https://cdn.example.com data:; script-src 'self'",
         },
+        // Only when you terminate HTTPS yourself:
+        // { key: "Strict-Transport-Security", value: "max-age=63072000; includeSubDomains" },
       ],
     },
     {
@@ -751,6 +786,10 @@ raising this number burns through memory quickly; trying to solve a site with
 tens of thousands of paths from here is the wrong layer — the right place is
 `cache().data`.
 
+**Ceiling 800.** A higher value is clamped to 800 with a warning at load.
+In-process HTML plus compressed bodies also cannot exceed 256 MB; config
+cannot raise that budget.
+
 ### `cache().data`
 
 The upstream data cache (`withDataCache`). Details:
@@ -758,7 +797,7 @@ The upstream data cache (`withDataCache`). Details:
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `maxEntries` | `number` | `10000` | The LRU entry limit. The limit is high because JSON is tens of times smaller than HTML. |
+| `maxEntries` | `number` | `10000` | The LRU entry limit. The limit is high because JSON is tens of times smaller than HTML. **Ceiling 20,000**; a higher value is clamped with a warning. |
 | `staleFactor` | `number` | `10` | For how many TTLs an entry stays usable after the TTL expired. `0` → no stale serving. |
 
 ### `cache().trackUpstream`
@@ -1003,13 +1042,13 @@ prewarm: {
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `onVisit` | `true \| false \| object` | off | Visit-driven warming |
-| `onVisit.perPage` | `number` | `20` | At most how many links per page (top to bottom) |
-| `onVisit.concurrency` | `number` | same as classic | Parallel workers |
-| `onVisit.rps` | `number` | same as classic | Requests per second cap; `0` unlimited |
+| `onVisit.perPage` | `number` | `20` | At most how many links per page (top to bottom). **Ceiling 20** |
+| `onVisit.concurrency` | `number` | `2` | Parallel workers. **Ceiling 2** |
+| `onVisit.rps` | `number` | `2` | Requests per second cap. **Ceiling 2**; `0` is clamped to 2 as well |
 
 ```js
 prewarm: {
-  onVisit: { perPage: 20, rps: 4 },
+  onVisit: { perPage: 20, rps: 2 },
 }
 ```
 
@@ -1106,10 +1145,11 @@ and no warning is printed.
 | Variable | Who reads it | Default | Meaning |
 | --- | --- | --- | --- |
 | `NODE_ENV` | everywhere | `production` (start/build), `development` (dev) | Determines the dev overlay, EJS cache, manifest re-reading, route error behaviour and prewarm defaults. `jskelet dev` sets it itself — `cross-env` is not needed. |
-| `PORT` | `startServer` | `3000` | Port to listen on |
+| `PORT` | `startServer` | `3000` | Port to listen on. If busy, the process refuses to start; `jskelet start|dev --murder` kills the listener |
 | `HOST` | `startServer` | `::` | Interface to bind to. The default listens dual-stack (IPv6 + IPv4); it falls back to `0.0.0.0` where IPv6 is unavailable |
 | `JSKELET_SECRET` | `jskelet/cookies` | — | The signed cookie secret. Read when `security.cookieSecret` is not set; if neither exists, the signed cookie API throws. [12](./12-dashboards-and-sessions.md) |
-| `DEV_TOKEN` | `devGate`, `prewarm` | — | If set, every request without a token gets a 404. Prewarming carries the token as a cookie. [09](./09-dev-tools.md) |
+| `DEV_GATE` | `devGate` | off | `1` turns the gate on, `0` turns it off even when config enabled it. `DEV_TOKEN` alone does not turn it on. [09](./09-dev-tools.md) |
+| `DEV_TOKEN` | `devGate`, `prewarm` | — | The secret expected while the gate is on. If it is missing, or the gate is off, the site stays public. Prewarming carries the token as a cookie only while the gate is on. [09](./09-dev-tools.md) |
 | `JSKELET_ADMIN` | `createApp` | — | When set, turns the admin panel on; `0` turns off a panel enabled in the config. The env wins because the panel is usually opened once during an incident. [06](./06-caching.md) |
 | `JSKELET_LOG_BUCKET` | `logs.s3` | — | Log target: bucket or `bucket/prefix` path. With credentials, the sink turns on automatically |
 | `JSKELET_S3_BUCKET` | `logs.s3` | — | Bucket when `JSKELET_LOG_BUCKET` is unset; joins with `JSKELET_S3_KEY_PREFIX` |

package/docs/en/08-build.md

@@ -174,8 +174,10 @@ a new utility is written. Changes are coalesced over 120 ms.
 
 ## Client JS — esbuild
 
-Every `.js` file inside `client/entries/*.js` is an entry. If the directory does
-not exist or is empty, the step is skipped.
+Every source file under `client/entries/*.{js,ts,mts}` is an entry (no `.tsx`).
+The manifest key is always `*.js` (`main.ts` → `main.js`). Multiple extensions
+for the same stem fail the build. If the directory does not exist or is empty,
+the step is skipped.
 
 esbuild settings:
 
@@ -185,7 +187,7 @@ esbuild settings:
 | `format` | `esm` | `type="module"` scripts |
 | `target` | `chrome111`, `edge111`, `firefox111`, `safari16.4` | The lower bound of the ESM + dynamic import + `IntersectionObserver` island model; transpiling to anything older grows the output without winning a single visitor |
 | `minify` | `true` | — |
-| `sourcemap` | `true` | Diagnostics in the browser |
+| `sourcemap` | only when `NODE_ENV=development` | Production builds do not publish `.map` files under `public/assets` |
 | `entryNames` | `[name].[hash]` | `immutable` cache |
 | `chunkNames` | `chunks/[name].[hash]` | — |
 | `legalComments` | `none` | — |
@@ -196,17 +198,19 @@ The output lands under `public/assets/js/` and is cleaned first on every pass.
 ### The `@/` alias
 
 On the esbuild side, `@/` resolves to the project root and extension completion
-is performed (`.js`, `.mjs`, `.json`, `/index.js`). The same behaviour as
-`alias-hooks.mjs` on the Node side, so the modules under `lib/` can use the same
-import style both on the server and in the browser.
+is performed (`.js`, `.mjs`, `.ts`, `.mts`, `.json`, `/index.js`, `/index.ts`).
+Node `alias-hooks.mjs` resolves only `.js` / `.mjs` / `.json` on the server, so
+shared `@/lib` modules must stay `.js`. Client-only `.ts` imports work on the
+esbuild path.
 
 ### Inlining `clientEnv`
 
 There is no `process` in the browser; modules shared with the server still read
 `process.env`. The keys declared through `config.clientEnv` plus `NODE_ENV` are
 defined as a single object at build time, which means that reading a key not in
-the list returns `undefined` instead of crashing. Details:
-[07-configuration.md](./07-configuration.md).
+the list returns `undefined` instead of crashing. Secret-like key names
+(`SECRET`, `API_KEY`, …) fail the build; names containing `PUBLIC` /
+`PUBLISHABLE` are exempt. Details: [07-configuration.md](./07-configuration.md).
 
 ### Manifest keys
 
@@ -285,7 +289,7 @@ Local file names:
   `0 0 256 256` (recommended for Phosphor / `icon()` compatibility).
 - The scanned directories default to `views`, `client`, `routes`, `lib`,
   `features`, `shared`; they can be changed with `icons.scan`. Scanned
-  extensions: `.ejs`, `.jsk`, `.js`, `.mjs`.
+  extensions: `.ejs`, `.jsk`, `.js`, `.mjs`, `.ts`, `.mts`.
 - Weights: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. An
   unrecognised weight counts as `regular`.
 
@@ -355,7 +359,9 @@ and `image()` falls back to the original file. It never runs on a watch pass.
 When `images.remote.allowHosts` is set, `createApp` mounts `/_jskelet/image`.
 CMS / CDN covers never enter the build, so `image()` rewrites those host URLs to
 `?url=&w=`; the endpoint encodes webp with sharp and stores files under
-`.jskelet/image-cache/`. Details: [07-configuration.md](./07-configuration.md).
+`.jskelet/image-cache/`. Upstream fetch follows redirects manually: every hop is
+re-checked against the allowlist and private IP / DNS rules (open-redirect SSRF
+is closed). Details: [07-configuration.md](./07-configuration.md).
 
 ## Precompress
 

package/docs/en/09-dev-tools.md

@@ -23,6 +23,11 @@ jskelet dev
 (suppresses the build banner) and, if a TTY is present, `JSKELET_COLOR=1`
 (forces color on piped output).
 
+If the listen port (`PORT`, default `3000`) is already taken, the server
+**does not start**; the error line includes the PID and a `--murder` hint.
+`jskelet dev --murder` kills the listener and binds the same port (for a
+process left running in another terminal).
+
 Startup order: banner → build steps → server ready → `Ready` summary. The
 summary is printed once both the build and the server are ready; otherwise it
 got buried among the build lines arriving afterwards.
@@ -75,7 +80,7 @@ WATCH_DIRS = [
 The `jskelet.config.mjs` file itself is watched as well: when the config
 changes, both the server and the build must come up with the new settings.
 
-Watched extensions: `.js`, `.mjs`, `.json`, `.ejs`.
+Watched extensions: `.js`, `.mjs`, `.json`, `.jsk`, `.ejs`.
 
 `views` is watched too, because most components live in
 `views/components/**.js` and, since those modules are imported into the server
@@ -298,11 +303,20 @@ production process.
 
 ## Dev gate — `DEV_TOKEN`
 
-To hide an environment that is not public yet: while `DEV_TOKEN` is set,
-**every** request without the token gets a 404.
+To hide an environment that is not public yet. **The framework does not require
+the token:** a `DEV_TOKEN` sitting in the environment does not lock the site.
+You turn the gate on.
 
 ```bash
-DEV_TOKEN=a-long-random-string npm start
+DEV_GATE=1 DEV_TOKEN=a-long-random-string npm start
+```
+
+The same thing from config:
+
+```js
+export default {
+  devGate: true,
+};
 ```
 
 Access:
@@ -323,10 +337,12 @@ Behavior:
   `/site.webmanifest`, `/favicon.ico`. If your health check lives at a different
   path, remember to add it to this list, otherwise your orchestrator will see a
   404.
-- Without `DEV_TOKEN` the middleware is entirely disabled and costs nothing in
-  production.
-- Since warming makes requests to its own server, it carries the token as a
-  cookie; without it every page gets a 404 and the cache never fills up
+- While `devGate` is off (the default) or `DEV_TOKEN` is empty, the middleware
+  passes the request through. A `DEV_TOKEN` that leaked into a production task
+  does not ask visitors for a token; startup prints a warning.
+- `DEV_GATE=0` turns the gate off even when config says `devGate: true`.
+- While the gate is on, warming carries the token as a cookie; without it every
+  page gets a 404 and the cache never fills up
   ([06-caching.md](./06-caching.md)).
 
 In the middleware chain the gate sits after `headers` and **before**

package/docs/en/10-deployment.md

@@ -23,6 +23,10 @@ runs the build itself. In a Docker image the build has already happened, so this
 is a no-op; the point is that someone running `npm start` directly does not end
 up with an unstyled page.
 
+If the listen port is already taken, the process **does not start** (PID + hint).
+`jskelet start --murder` kills that listener and binds — useful for a leftover
+dev process; production orchestrators usually do not need it.
+
 When the server is ready it prints a single line:
 
 ```
@@ -47,7 +51,7 @@ considering in production:
 | `HOST` | `0.0.0.0` | Only if you need to listen on IPv4 alone; the `::` default already listens dual-stack |
 | `PREWARM_MAX` | Depends on site size | Number of pages warmed at startup |
 | `PREWARM_INTERVAL_SECONDS` | `0` or a long value | If you want to keep never-visited pages warm |
-| `DEV_TOKEN` | Staging only | Hides an environment that is not public yet |
+| `DEV_GATE` + `DEV_TOKEN` | Staging only | Hides an environment that is not public yet. The token alone does not lock the site |
 | `JSKELET_S3_*` | If you write access logs to S3 | Bucket + credentials; details in [07](./07-configuration.md) |
 
 When a file or S3 sink is enabled in production, the HTTP access log middleware
@@ -64,7 +68,8 @@ Using both sources together blurs which value actually applies; not shipping a
 `.env` in the prod image is the cleanest option.
 
 **Secret keys must not go into the `clientEnv` list:** those values are embedded
-into the client bundle as plain text ([08-build.md](./08-build.md)).
+into the client bundle as plain text ([08-build.md](./08-build.md)). Secret-like
+names (`SECRET`, `API_KEY`, …) now fail the build.
 
 ## Docker
 
@@ -152,16 +157,11 @@ The build stage produces these itself with `npx jskelet build`.
 
 The examples in this repo pull jskelet with `"jskelet": "file:../.."` rather
 than from npm. In tools like Coolify, Railway or Render, if you set the "base
-directory" to `examples/marketing`, the build context becomes only that
-directory, `../..` falls outside the context, and installation fails at
-`npm ci`. The correct setting: **base directory `/`**, Dockerfile location
-`/examples/marketing/Dockerfile`. The working example is in
-`examples/marketing/Dockerfile` and assumes the repo root as its context:
-
-```bash
-docker build -f examples/marketing/Dockerfile -t jskelet-marketing .
-docker run --rm -p 3000:3000 -e SITE_URL=https://example.com jskelet-marketing
-```
+directory" to `examples/blog`, the build context becomes only that directory,
+`../..` falls outside the context, and installation fails at `npm ci`. The
+correct setting: **base directory `/`** (the repo root) and adapt the
+multi-stage Dockerfile above to the app directory — or install jskelet as a
+normal npm dependency and use the app directory as the context.
 
 In your own application jskelet will be an ordinary dependency, so this
 constraint does not apply; the multi-stage image above is enough.
@@ -171,7 +171,7 @@ constraint does not apply; the multi-stage image above is enough.
 The framework does **not** add a ready-made health check endpoint; you have to
 put it in your own route. Since the default `devGateBypass` list contains
 `/api/healthcheck`, using that name is the least surprising option: it stays
-reachable even in an environment with `DEV_TOKEN` set.
+reachable even while the dev gate is on.
 
 ```js
 // routes/00-health.mjs
@@ -328,7 +328,7 @@ goes up, the work per request drops to almost zero.
 - [ ] `hooks.prewarmPaths()` puts the most important pages first
 - [ ] CSP and security headers are defined in `headers()`
 - [ ] A health check endpoint exists and is in the `devGateBypass` list
-- [ ] `DEV_TOKEN` is set on staging and **not set** in production
+- [ ] Staging has `DEV_GATE=1` and `DEV_TOKEN`; production leaves the gate **off**
 - [ ] The reverse proxy forwards `Accept-Encoding` and does not do its own
       compression
 - [ ] There are no secret keys in the `clientEnv` list