docs: correct the CSP contrast on the docs site too

vivek7405 · vivek7405 · commit 33e8cd5998f3 · 2026-08-06T10:58:11.000+05:30
The deployment page carried the same framework-versus-app nonce contrast
the source comment now denies, in nearly the same words as the blog
sentence already fixed. style-src has no nonce source, so unsafe-inline
admits every inline style including WebJs's own head rule, and the page
now says that before listing what makes the allowance hard to give up.

The global-error guidance said an inline style there must carry the
nonce. Under the default policy that is inert for style and load-bearing
only for script, so both places now say which is which.

The scaffold-sync rule went too far the other way. Several cards do carry
a prune note, and they are the ones where removal spans paths or another
card depends on them, so the rule now describes that shape instead of
forbidding it. AGENTS.md also documents selective pruning, which a
blanket prohibition contradicted.
diff --git a/.claude/skills/webjs-scaffold-sync/SKILL.md b/.claude/skills/webjs-scaffold-sync/SKILL.md
@@ -210,10 +210,14 @@ Run the mandatory generate + boot + check verifications in PARALLEL when more th
    test, the counterfactual).
 6. Respect the prose-punctuation invariant (#11) in every comment and doc, and
    keep each demo densely commented (a header stating the webjs concept + the
-   why, and inline comments on the non-obvious idiom). Do NOT add a per-demo
-   prune line: `npm run gallery:clear` sheds the whole gallery in one step, so
-   the full-stack demos deliberately carry no such comment. The scaffold teaches
-   by its comments, and a thin demo is a bug.
+   why, and inline comments on the non-obvious idiom). Add a prune note where
+   removal is NOT obvious, which is what the demos that carry one do: a card
+   spanning several paths, or one that another card depends on (the auth and
+   server-actions cards name each other). A self-contained demo needs none,
+   since `AGENTS.md` tells the app-building agent to delete the
+   `app/features/<x>` route and its `modules/<x>` and `npm run gallery:clear`
+   sheds the lot. The scaffold teaches by its comments, and a thin demo is a
+   bug.
 
 ## Audit-mode procedure (sweep the scaffold for drift)
 
diff --git a/AGENTS.md b/AGENTS.md
@@ -290,7 +290,7 @@ Default export receives `{ children, params, searchParams, url }`, must embed `c
 
 ### Error / loading / metadata routes
 
-`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<style>`/`<script>` in it must carry the nonce via `cspNonce()`. `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML.
+`error.{js,ts}` default-exports `({ error, ...ctx }) => TemplateResult` (catches sibling-page / deeper render errors, innermost wins, prod sends only `error.message`). `loading.{js,ts}` wraps the sibling page in `Suspense` with an immediately-flushed fallback. `forbidden.{js,ts}` / `unauthorized.{js,ts}` render the nearest 403 / 401 boundary for a thrown `forbidden()` / `unauthorized()` (#848). Two **root-only** boundaries (`app/` root exactly): `global-error.{js,ts}` is the app-wide catch-all tried after the nested `error` boundaries are exhausted, and it renders its **own** `<!doctype><html><body>` document (returned verbatim, since a root-layout failure is when it fires). Because it is returned verbatim (no framework `<head>` splice), it ships **no importmap or boot script**, so keep it **static HTML with no components/hydration** (a last-resort page must not depend on the module system that may have just failed); under an opt-in CSP, an inline `<script>` in it must carry the nonce via `cspNonce()` (an inline `<style>` needs one only if you tighten `style-src`, since the default allows inline style outright). `global-not-found.{js,ts}` renders for an unmatched-anywhere URL when no `not-found` matches. `not-found` is nearest-wins from the throwing page's chain (#848 fixed the prior root-only behavior). Metadata routes (`sitemap`, `robots`, `manifest`, `icon`, `apple-icon`, `opengraph-image`, `twitter-image`) live at app root or static segments only and default-export a possibly-async function; `sitemap(entries)` / `sitemapIndex(sitemaps)` from `@webjsdev/server` serialize spec-valid XML.
 
 ### Route handlers (`app/**/route.{js,ts}`)
 
diff --git a/website/app/docs/deployment/page.ts b/website/app/docs/deployment/page.ts
@@ -79,7 +79,7 @@ npm run start -- --port 8080</code-block>
     <code-block>&#123;
   "webjs": &#123; "csp": true &#125;
 &#125;</code-block>
-    <p><code>true</code> turns on a strict-by-default policy: <code>script-src 'nonce-&lt;minted&gt;' 'strict-dynamic' 'self' https:</code> plus <code>default-src 'self'</code>, <code>object-src 'none'</code>, <code>frame-ancestors 'self'</code>, and an inline-style allowance. That last one is there for the styles your app puts in the document, which do not carry a nonce: a light-DOM component's <code>&lt;style&gt;</code> block in <code>render()</code>, a shadow component's <code>static styles</code>, an inline <code>&lt;style&gt;</code> written by a page or layout, and <code>style="…"</code> attributes, which no nonce can reach at all since nonces apply to elements rather than attributes. The framework's own head style rule carries the nonce. On every request the framework mints a CSPRNG nonce (16 random bytes, base64), stamps it on every inline <code>&lt;script&gt;</code>, the importmap, and the <code>modulepreload</code> hints it emits (the same value <code>cspNonce()</code> returns during SSR), and sets the header carrying that exact nonce. The nonce on the header and the nonce on the scripts are one minted value, so there is no drift, and it changes every request.</p>
+    <p><code>true</code> turns on a strict-by-default policy: <code>script-src 'nonce-&lt;minted&gt;' 'strict-dynamic' 'self' https:</code> plus <code>default-src 'self'</code>, <code>object-src 'none'</code>, <code>frame-ancestors 'self'</code>, and an inline-style allowance. That last one is needed because <code>style-src</code> carries no nonce source at all, so every inline style is admitted by <code>'unsafe-inline'</code>, the framework's own head rule included. What keeps it hard to give up is the style your app puts in the document: a light-DOM component's <code>&lt;style&gt;</code> block in <code>render()</code>, a shadow component's <code>static styles</code>, an inline <code>&lt;style&gt;</code> written by a page or layout, and <code>style="…"</code> attributes, which no nonce could reach even if the directive honoured one, since nonces apply to elements rather than attributes. On every request the framework mints a CSPRNG nonce (16 random bytes, base64), stamps it on every inline <code>&lt;script&gt;</code>, the importmap, and the <code>modulepreload</code> hints it emits (the same value <code>cspNonce()</code> returns during SSR), and sets the header carrying that exact nonce. The nonce on the header and the nonce on the scripts are one minted value, so there is no drift, and it changes every request.</p>
     <p>For a custom policy, give an object. <code>directives</code> is merged over the strict defaults (override one directive without restating the rest; a <code>null</code> value drops a default directive), and <code>reportOnly: true</code> emits <code>Content-Security-Policy-Report-Only</code> for a staged rollout:</p>
     <code-block>&#123;
   "webjs": &#123;
diff --git a/website/app/docs/error-handling/page.ts b/website/app/docs/error-handling/page.ts
@@ -101,7 +101,7 @@ export default function GlobalError({ error }: { error: Error }) {
   ${'`'};
 }</code-block>
 
-    <p>Keep <code>global-error.ts</code> static (no components / hydration): it is returned verbatim with no importmap or boot script, so it must not depend on the module system that may have just failed. Under an opt-in CSP, give any inline <code>&lt;style&gt;</code> the <code>cspNonce()</code>.</p>
+    <p>Keep <code>global-error.ts</code> static (no components / hydration): it is returned verbatim with no importmap or boot script, so it must not depend on the module system that may have just failed. Under an opt-in CSP, give any inline <code>&lt;script&gt;</code> the <code>cspNonce()</code>. An inline <code>&lt;style&gt;</code> needs one only if you tighten <code>style-src</code>, since the default policy allows inline style outright.</p>
 
     <p><code>global-not-found.ts</code> renders for a URL that matches nothing anywhere, when no <code>not-found.ts</code> applies.</p>
 
