@piercebarney/whs-eleventy 2026.9.1

package/standard/core.md

@@ -0,0 +1,1493 @@
+# Web project house style — CORE (stack-agnostic)
+
+**Version:** 2026-09-01 · **Status:** active
+
+This is the stack-agnostic contract every web project follows, regardless of
+framework, host, or CSS system. It says **what** must be true, with concrete
+specs. It never says **how** — that lives in one implementation doc per stack
+(`stacks/eleventy-netlify.md`, `stacks/phoenix.md`, `stacks/sveltekit.md`).
+
+**How to use this:** at project start, run the stack-selection flow
+(`#adopting`). Then load **this file plus the one `stacks/*.md` file** matching
+the project's `framework:` key, and read the `styling` subsection named by its
+`css:` key. Where an impl doc is silent on a contract here, this file governs
+unchanged. Where they appear to conflict, that is a bug — fix one doc, never
+fork the principle.
+
+Each chapter: **Contract** (what MUST be true) · **Specs** (concrete
+values/thresholds) · **Rationale** (why, when non-obvious) · **Verify** (how the
+gate or audit page proves it) · **Implementation** (pointer to your stack doc).
+The two closing chapters (`#out-of-scope`, `#anti-patterns`) are reference lists,
+not contracts.
+
+Chapter headings are `## <slug> — <Title>`. The `<slug>` is a frozen ID; cite it
+as `core.md#<slug>`. Never cite by number.
+
+---
+
+# Part A — Repository & stack
+
+## repo-hygiene — Repository hygiene
+
+**Contract.** The repo is legible: two docs and no third, a clean ignore list, a
+committed lockfile, one default branch, small self-contained changes.
+
+**Specs.**
+- Exactly two prose docs: `README.md` (what the site is + how to run and deploy
+  it — the narrative) and `CLAUDE.md` / `AGENTS.md` (the operating rules an
+  assistant follows, including this project's stack-selection block per
+  `#adopting`). No `PROJECT.md` or third rules file.
+- `.gitignore` covers: dependencies, build output, local caches, `.env`,
+  OS cruft (`.DS_Store`). Commit `.env.example`.
+- Commit the dependency lockfile.
+- Default branch is **`main`**.
+- Conventional-commit messages; one logical change per commit (and per pull
+  request, on projects that use them — see `#ci-cd`).
+
+**Verify.** Manual review. The audit page's infra tab flags a committed `.env`,
+a missing lockfile, a non-`main` default branch.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## runtime-pin — Runtime & toolchain pinning
+
+**Contract.** The language/runtime version is pinned in exactly one file — the
+one the stack's tooling reads natively — and nowhere else.
+
+**Specs.**
+- One source of truth for the runtime version. Not two (e.g. not a version file
+  *and* a host setting).
+- CI and local dev both read that same file.
+
+**Rationale.** Two version sources drift; a build that passes locally then fails
+in CI on a different runtime is the failure this prevents.
+
+**Verify.** The audit page compares the pinned version to the running version.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## config-idiom — Configuration is idiomatic and minimal
+
+**Contract.** Configuration leans on framework defaults, reads as a table of
+contents, and uses one mechanism per concern.
+
+**Specs.**
+- Prefer defaults; only configure what genuinely differs.
+- When a config file starts juggling many responsibilities, split the bodies
+  into modules that the main file registers — the main file stays a manifest.
+- One mechanism for redirects and headers (not a mix of a config file and stray
+  sidecar files).
+- Environment access is centralised (see `#seo-urls` for the build-context
+  module and `#secrets` for tokens).
+
+**Verify.** Review.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part B — Content & rendering
+
+## content-model — Externalized, validated content
+
+**Contract.** Page content lives in structured data separate from templates, and
+a build-time schema gate hard-fails the build on invalid content.
+
+**Specs.**
+- User-visible copy (titles, descriptions, body prose, lists) is authored as
+  data, not embedded in markup. Templates render data and nothing else.
+- A validator runs before the build completes and **exits non-zero** on any
+  error, printing every error (not just the first), each as `path: expected X`.
+- Validation covers: required keys present; correct types; enum values; **unique
+  ids/slugs** (they become URLs and anchors); array lengths the markup depends
+  on; every page has a non-empty `title` and `meta_description` within length
+  bounds (see `#seo-meta`).
+- The same validator is runnable standalone (fast, no full build) and is part of
+  the one gate (`#the-gate`).
+- Where non-developers edit content, provide editor-time validation (a schema
+  the editor understands) in addition to the build gate; a Git-backed CMS over
+  the same data files is acceptable — a separate database for site content is
+  not. Where an **LLM agent** edits the data files directly, it follows a
+  documented per-project content-ops protocol: what it may change (the content
+  files, not code or structure), a pre-commit content check (the
+  content-relevant slice of the gate), and a `content:` commit convention. See
+  your stack's impl doc.
+- **Drafts** are a data flag. A draft renders in local and preview builds
+  (reviewable) but is excluded from the production build and the sitemap.
+  Publishing is removing the flag.
+- The project records its target publishing rate for new content pages in
+  `CLAUDE.md`. Bulk-publishing many pages at once depresses indexing; pace
+  deliberately.
+
+**Rationale.** Content that lives in templates can't be validated, can't be
+edited safely by non-developers, and drifts from its own stated facts (a
+calculator whose copy says "18%" while the code uses 15%).
+
+**Verify.** The gate fails the build on invalid content. The audit page shows
+validation status.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## rendering — Rendering & progressive enhancement
+
+**Contract.** Core content and navigation work with no client JavaScript. Client
+JS enhances; it never gates the essentials. Any logic that renders on both the
+server and the client is written once.
+
+**Specs.**
+- The server-rendered (or prerendered) HTML is complete: a crawler or a
+  JS-disabled browser gets the full content and working links.
+- Client JS adds interactivity (filtering, live recompute, a quiz). A
+  `<noscript>` note covers only the interactive affordances, never the content.
+- If a feature re-renders content in the browser from the same data the build
+  used, there is **one renderer module** shared by both sides — never two copies
+  of the same logic.
+- Nothing that matters (core content, primary CTA) blocks on a network fetch.
+  Live data arrives after first paint and degrades to a clear fallback state
+  (see `#third-parties`).
+
+**Verify.** Load a key page with JS disabled: content and links present.
+Grep for duplicated render logic.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part C — Assets & styling
+
+## assets — Self-contained assets
+
+**Contract.** Every static asset is served from your own origin. Generated
+assets are generated from the brand source, never hand-authored, never allowed
+to go stale.
+
+**Specs.**
+- Fonts, CSS, JS, icons, and images are self-hosted. **No CDN links, no Google
+  Fonts** — there is no feature-need exception for a static asset. A system font
+  stack also satisfies "no external font origin".
+- Fonts, when custom, are subset to the scripts actually used, declared with
+  `font-display: swap` and a metric-matched fallback, and the above-the-fold
+  face is preloaded. **Verify the subset actually covers the site's text** — a
+  mis-scoped subset (e.g. Cyrillic-only) loads with no error and silently falls
+  back to the system stack, so the custom font is dead weight nobody notices.
+- The web manifest is served as `application/manifest+json` (some hosts default
+  a `.webmanifest` to `application/octet-stream`; set the header).
+- Favicons, app icons (`apple-touch-icon`), the web manifest, and OG images are
+  **generated from the brand token source** (`#brand-source`) as part of the
+  build — never a hand-made file, never a remote request. They are gitignored
+  and regenerated, or committed with a CI check that fails on `git diff` after
+  regeneration.
+- Raster images ship with explicit `width`/`height` (or `aspect-ratio`).
+
+**Rationale.** Self-hosting buys reproducible builds, no third-party runtime
+failure, and a short privacy policy. Generating brand assets means a brand
+change can't leave a stale favicon or share card behind.
+
+**Verify.** The link/reference check (`#internal-links`) fails on any external
+origin in the output not in the manifest (`#third-parties`) and on any missing
+referenced asset. The audit page shows the generated-asset gallery.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## styling — Styling constants
+
+**Contract.** One CSS system per project, one token source, strict-CSP-safe, and
+contrast-correct at the token level.
+
+**Specs.**
+- Pick one CSS approach and record it in `CLAUDE.md` (`css:` key). Options are
+  defined per stack in the impl doc's `styling` section.
+- **One token source** feeds everything (`#brand-source`): the live stylesheet,
+  generated OG cards, generated icons, and `theme-color` all read the same
+  colours/type/spacing.
+- **Strict-CSP-safe:** no `style-src 'unsafe-inline'`, no inline `style=`
+  attributes in templates, no per-page `<style>` blocks. Utility-class systems
+  (Tailwind) are fine; inline style strings are not.
+- Contrast meets WCAG AA. When a pair fails, fix the **token**, not the usage.
+- Theme is applied via a data attribute set before first paint (`#theme`).
+- A second stylesheet only for a genuinely separable widget, justified in a
+  comment.
+
+**Verify.** CSP has no `'unsafe-inline'` for styles. The audit page flags any
+sub-AA token pair.
+
+**Implementation.** See your stack's impl doc `styling` section (one subsection
+per supported CSS system).
+
+---
+
+# Part D — Client behaviour
+
+## client-logic — Client-side logic
+
+**Contract.** Any logic that computes a result a user relies on is a pure,
+independently testable function. Page code only wires it to the DOM.
+
+**Specs.**
+- A formula, unit conversion, price, tax, or date calculation lives in its own
+  module as a pure function (inputs → result, no DOM, no globals), loadable by
+  both the browser and the test runner.
+- Page/component code does only: read inputs → call the pure function → format →
+  write the DOM.
+- **The wiring is CSP-safe** — no inline `<script>`, no `on*=` handlers; the
+  baseline `script-src 'self'` (`#security-headers`) rejects both. It is a
+  loaded script file. For a per-page calculator, the browser-only wiring can sit
+  in a `typeof document !== "undefined"` block inside the *same* pure module, so
+  one file both loads DOM-free in the test runner and wires the page in the
+  browser. (An unhashed inline script is only an option on a stack that hashes
+  it into the CSP — most static setups can't.)
+- Feature-detect and guard (`if (el) …`, `try/catch` around storage APIs).
+- **No client-side error tracking by default.** Correctness is covered by the
+  domain tests (`#domain-tests`), not by watching production logs. (Adding error
+  tracking is adding a third-party — `#third-parties`.)
+
+**Verify.** `#domain-tests` covers the pure functions. Review flags a formula
+computed inline in a template, an inline `<script>` or `on*=` handler in the
+output, or DOM code in the "pure" module's top level.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## theme — Light/dark theme
+
+**Contract.** The theme is set before first paint, respects the OS preference
+when unset, and persists the user's choice.
+
+**Specs.**
+- A tiny script, first thing in `<head>`, reads the stored preference and sets a
+  root data attribute before paint, wrapped in `try/catch`. Under the baseline
+  `script-src 'self'` it is a **separate render-blocking file** (`<script
+  src="/theme-init.js">`, no `defer`) — or a hashed inline block on a stack that
+  wires hashes into the CSP. An unhashed inline script is blocked.
+- With no stored preference, fall back to `prefers-color-scheme`.
+- The toggle persists the choice to local storage (or the stack's equivalent).
+- `theme-color` (light + dark) and `color-scheme: light dark` values come from
+  the brand source (`#brand-source`).
+
+**Rationale.** Setting the theme after paint causes a flash; not persisting it
+surprises the returning visitor.
+
+**Verify.** Reload in each theme — no flash. The audit page shows the resolved
+`theme-color` values.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part E — SEO & metadata
+
+## seo-urls — Canonical & absolute URLs
+
+**Contract.** Every canonical, Open Graph, and sitemap URL is absolute and
+anchored to the **production** origin, on every build in every context. One
+module is the single reader of environment / deploy context.
+
+**Specs.**
+- A `site` config holds `{ name, url }` where `url` is the production origin.
+  Canonical/OG/sitemap URLs always use it — never the current deploy's origin.
+- Exactly one `<link rel="canonical">` per page, absolute, trailing slash
+  matching the permalink.
+- A single **build-context module** is the only place that reads environment
+  variables for the site (build scripts may read their own tokens — `#secrets`).
+  It exposes at least `{ target, isProduction, commit }`. `isProduction` is
+  driven by a variable **you set** on the deploy path, not inferred from the
+  host.
+- Everything context-dependent (robots rules, the `noindex` flag, audit-page
+  build facts) derives from that module.
+
+**Verify.** Grep the output for the production origin in every canonical/OG/
+sitemap URL. Grep the codebase: exactly one file reads `process.env` / the
+env equivalent for the site.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## seo-meta — Per-page metadata, Open Graph & Twitter
+
+**Contract.** Every page has a validated title and description and a complete,
+data-driven Open Graph + Twitter tag set. Tags are emitted by one shared
+implementation, never hand-written per page.
+
+**Specs.**
+- `title` and `meta_description` are required per page and validated for
+  non-emptiness and length (`#content-model`).
+- One shared head component/partial emits, on **every** page:
+
+  | Tag | Value |
+  |---|---|
+  | `og:type` | `website` by default; `article` for dated content |
+  | `og:title` | the page title (a `" — Site"` suffix may be dropped) |
+  | `og:description` | the page `meta_description` |
+  | `og:url` | absolute, production origin, identical to the canonical |
+  | `og:site_name` | the site name |
+  | `og:locale` | `en_US` (or the real locale) |
+  | `og:image` | absolute URL to a self-hosted image (`#og-image`) |
+  | `og:image:alt` | short description of the image |
+  | `twitter:card` | `summary_large_image` when the image is ≥1200×630, else `summary` |
+  | `twitter:title` / `twitter:description` / `twitter:image` | mirror the `og:*` values |
+
+- `article`-type pages additionally emit `article:published_time` /
+  `article:modified_time` (ISO 8601), `article:author`, and
+  `article:section` / `article:tag` where the data has them.
+- `<html lang="…">` is set; one `<h1>` per page; headings ordered, no level
+  skipped.
+
+**Verify.** Paste a deployed URL into an OG debugger; the audit page renders the
+full tag set per page. Validation fails a page with a missing/over-length
+`meta_description`.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## og-image — OG image spec & generation
+
+**Contract.** Every page resolves to a self-hosted, absolute, production-origin
+OG image that is generated from the brand tokens at build time.
+
+**Specs.**
+- **1200×630** (1.91:1), under ~1 MB, **PNG or JPG — not SVG, not WebP** (some
+  scrapers reject them), served from `/og/`.
+- Absolute, production origin, on every build regardless of target.
+- A site-wide `default` image is used whenever a page supplies none; per-page
+  override via a frontmatter/data key resolved so the template reads one value.
+- Cards are **generated from the brand token source** (`#brand-source`) as part
+  of the build. Never hand-drawn in an editor. Never committed stale (or
+  committed with a CI `git diff --exit-code` gate after regeneration).
+- The generator is cache-aware (skips cards whose inputs are unchanged) so it is
+  cheap on incremental rebuilds.
+
+**Verify.** The audit page's OG gallery shows every card at true 1.91:1 with its
+dimensions and file size; the link check fails on a missing `og:image` file.
+
+**Implementation.** See your stack's impl doc, same slug — the generation
+toolchain differs substantially per stack.
+
+## structured-data — JSON-LD
+
+**Contract.** Every page emits valid JSON-LD appropriate to its type.
+
+**Specs.**
+- One block per page type: `WebSite` (home), plus `WebApplication` / `Article` /
+  `Product` / `BreadcrumbList` / `Organization` as the page warrants.
+- Every block parses as JSON and carries the required fields for its declared
+  `@type`.
+- Built by serialising a data object, never hand-written string templating.
+- After any change to the JSON-LD shape, run it once through Google's Rich
+  Results Test (catches eligibility, which the offline parse check can't).
+
+**Verify.** The link/reference check asserts every `application/ld+json` block
+parses and has its `@type`'s required fields.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## sitemap-robots — Sitemap, robots, feeds
+
+**Contract.** `sitemap.xml`, `robots.txt`, and (for article sites) `feed.xml`
+are generated from the content set. None is hand-maintained.
+
+**Specs.**
+- `sitemap.xml`: indexable pages only, absolute URLs from the production origin,
+  `<lastmod>` from the content's date or git. Excludes the 404, redirects, the
+  audit page, and anything flagged non-collectable.
+- `robots.txt`: keyed on `isProduction` — in production, `Allow: /` +
+  `Disallow:` the audit page + `Sitemap:` line; in every non-production build,
+  `Disallow: /`.
+- `feed.xml` (article sites only): newest ~20 dated entries, absolute URLs and
+  IDs from the production origin, `updated` from the most recent entry; a
+  `<link rel="alternate" type="application/atom+xml">` in the head. Tool sites
+  with no dated content skip this.
+
+**Verify.** The output contains generated `sitemap.xml` and `robots.txt`; both
+parse; `robots.txt` content matches the build target.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## noindex — Non-production builds are un-indexable
+
+**Contract.** Every build that is not the production artifact is un-indexable,
+by three layers in order of reliance.
+
+**Specs.**
+1. **Build-time (primary):** when `isProduction` is false, the layout emits a
+   site-wide `<meta name="robots" content="noindex, nofollow">` and `robots.txt`
+   is `Disallow: /`. This travels with the artifact regardless of how it is
+   served. The same flag gates display ads (`#ads`) — they never load off a
+   non-production build.
+2. **Header backstop:** the host's response headers add `X-Robots-Tag: noindex`
+   for preview/branch contexts where the platform supports it. Treated as a
+   bonus — not relied on.
+3. **Canonical:** every page's canonical points at the production origin, so an
+   indexed stray still redirects search engines to production.
+
+**Verify.** Build with the target unset → output carries `noindex` meta and
+`Disallow: /`. Build for production → neither.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part F — Brand & audit
+
+## brand-source — Brand as single source of visual truth
+
+**Contract.** One file holds every brand primitive. The live CSS, the generated
+OG cards, and the generated favicons all consume it. A brand change flows to all
+three on the next build with no separate step.
+
+**Specs.**
+- One file (`brand.*` / a theme block / a tokens module) holds: brand
+  colour(s), accent, background, text colour, font family + file paths, and the
+  logo mark's path data.
+- The stylesheet consumes those tokens (via generated custom properties or the
+  framework's theme mechanism) and **never hardcodes a brand value**.
+- The OG-card renderer and the icon generator read the same file directly.
+- Hardcoding a brand colour/font/logo anywhere else — the stylesheet, `<head>`,
+  a card template, an icon file — is a **defect**.
+
+**Verify.** Grep for hex colours / font-family strings outside the brand file.
+The audit page renders swatches and the type scale from the brand file.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## audit-page — The audit page
+
+**Contract.** One non-crawlable page renders everything drift-prone in one
+place, with a summary that surfaces failures without clicking into every tab.
+
+**Specs.**
+- One route/page, excluded from collections, sitemap, and nav; `<meta
+  name="robots" content="noindex, nofollow">` unconditionally; an all-contexts
+  `X-Robots-Tag: noindex` header for its path; a `Disallow:` line in production
+  `robots.txt`.
+- **Contains nothing that would be harmful if public.** It is served as-is (or
+  rendered client-side from baked data), so treat it as readable by anyone who
+  finds the URL. Secret **presence** may appear as a boolean
+  (`TOKEN: present`); a secret **value** never appears. No client-side password
+  — for real locking use the host's auth, and still put nothing sensitive on it.
+- **Tabs**, not one long scroll, with: a persistent summary bar listing every
+  failed/warned check and its tab; a status dot per tab; a "show all" toggle for
+  find-in-page and printing.
+- Tabs cover: brand tokens + contrast flags + type scale; generated assets (OG
+  cards at true ratio with dimensions/size, favicons); link + privacy integrity
+  results; infrastructure config (repo introspection + optional live
+  host/CI-API checks + a manual checklist with committed `verifiedOn` dates);
+  build facts (target, commit, generator timestamps); **Compliance** (the
+  per-chapter `PASS` / `FAIL` / `MANUAL` grid from `#compliance`, plus the
+  `standard-version` drift row). The summary bar counts non-`PASS` chapters
+  alongside failed checks.
+- The infrastructure checks run at build time following `#third-parties` rules
+  (cache the result, never fail the build if an API is down, stamp "as of …").
+  A subset runs as a deploy pre-flight that **hard-fails** on a cost- or
+  SEO-breaking mismatch and warns on the rest.
+
+**Rationale.** Out-of-repo config (a host build toggle, a DNS record, a search
+console verification) is the most drift-prone part of any project and nothing in
+the repo can enforce it. One surface makes drift visible.
+
+**Verify.** Open the page after a build; the summary bar is clean.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part G — Security, caching, privacy
+
+## security-headers — Security response headers
+
+**Contract.** Every response carries the baseline security header set, including
+a strict Content-Security-Policy. The CSP widens only to match the declared
+origin manifest, in one place, and is verified against that list.
+
+**Specs.**
+- Baseline headers on every response:
+  - `X-Content-Type-Options: nosniff`
+  - Framing denied: `X-Frame-Options: DENY` **or** `SAMEORIGIN` together with
+    `frame-ancestors 'none'` in the CSP
+  - `Referrer-Policy: strict-origin-when-cross-origin`
+  - `Permissions-Policy: geolocation=(), camera=(), microphone=()`
+- Baseline CSP (a fully self-contained site):
+  ```
+  default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; connect-src 'self'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'
+  ```
+- When `#third-parties` adds an origin, the matching directive (`connect-src` /
+  `script-src` / `img-src` / `frame-src`) widens to **exactly** those origins,
+  in the one header definition, nowhere else.
+- Display ads (`#ads`) are the one place the CSP widens substantially. That
+  relaxation is scoped to the ad directives, documented with a comment, and any
+  `'unsafe-inline'` it forces stays out of `default-src`.
+- HTTPS is enforced (HSTS via the platform or `force_ssl`). A platform-managed
+  HSTS header is not restated in the config.
+
+**Verify.** The link/reference check fails on any origin the CSP grants that is
+not in the origin manifest. (Not the reverse: a host or form processor is in
+the manifest — it sees visitor data — but is not a browser-resource origin, so
+it needn't appear in the CSP.) The audit page shows the **live** header set on
+`/` — i.e. what the host actually sends, so a loosened dashboard setting shows
+up there.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## caching — Cache headers & fingerprinting
+
+**Contract.** Cache lifetimes match mutability. `immutable` is only ever set on
+content-fingerprinted filenames. A changed URL ships a redirect from the old
+one.
+
+**Specs.**
+- HTML: `Cache-Control: public, max-age=0, must-revalidate` — never `immutable`.
+- Fingerprinted assets (content hash in the filename): `public, max-age=31536000,
+  immutable`.
+- Non-fingerprinted assets: a moderate `max-age` with `must-revalidate`.
+- A project either fingerprints its app CSS/JS (then caches it `immutable`) or
+  serves it un-fingerprinted with revalidation — pick one and apply it
+  consistently.
+- When a page's permalink changes, a `301` from the old path ships in the **same
+  change** as the rename.
+
+**Verify.** Review the header rules. The audit page / a link check flags a
+renamed permalink with no redirect.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## third-parties — External resources & the origin manifest
+
+**Contract.** Self-contained is the default. A genuine feature need may add an
+external resource, but every external touch is deliberate, declared, isolated,
+and degrades gracefully.
+
+**Specs.**
+- **The decision test, in order:**
+  1. Can the data be fetched at build time and baked in? If it changes slower
+     than you deploy — do that. No runtime origin, no CSP change, no key
+     exposure. Cache the response; commit a fallback fixture.
+  2. Does it need a secret (API key)? Then it **cannot** be called from the
+     browser — call it server-side (a server route, or a thin serverless proxy
+     that holds the key and forwards only the needed fields).
+  3. Is the feature still usable if the call fails or is blocked? It must be —
+     design the fallback state first (`AbortController` timeout, clear fallback,
+     never a permanent spinner; absent-not-broken with JS off; never blocks
+     first paint).
+  4. Only then add the origin to the manifest and widen the CSP.
+- **One canonical origin manifest** lists every external origin the site touches
+  — host, form handler, anything the steps above added — each as
+  `{ origin, purpose, dataSeen, loadedWhen }`.
+- The gate fails the build on any external origin in the output that is not in
+  the manifest, and on any mismatch between the manifest and the CSP.
+- A third-party `<script>` (last resort, no self-hostable equivalent) needs a
+  Subresource Integrity hash + `crossorigin`, is loaded lazily, and is never
+  render-blocking. It forfeits the strict-CSP / short-privacy benefits for that
+  page — note it in the commit message (and the PR, if any).
+- A **display-ad provider** is a declared third party. Its origins go in the
+  manifest; its full set of consequences (consent, CSP, CLS, non-prod gating,
+  `ads.txt`) is collected in `#ads`.
+- A **model / LLM provider** the project calls is a declared third party — its
+  origin in the manifest, its data-retention and training posture stated in
+  `dataSeen`. Because the call carries an API key it is server-side only (step 2
+  above); the full set of consequences is collected in `#llm-integration`.
+
+**Verify.** The link/reference check enforces the manifest ↔ output ↔ CSP
+agreement.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## privacy — Privacy posture
+
+**Contract.** The default is no tracking of any kind. Analytics, if the project
+needs it, is either privacy-first or consent-gated. The privacy page is
+generated from the origin manifest, never hand-written.
+
+**Specs.**
+- **Default posture:** no analytics, no cookies beyond a functional session, no
+  fingerprinting, no consent banner needed.
+- If analytics is required, one of:
+  - **privacy-first** — self-hosted (Plausible, GoatCounter) or server-log-based,
+    no cookie, no cross-site identifier; or
+  - **consent-gated** — a third-party analytics/tag manager (including GA/GTM) is
+    permitted **only** when it does not load or set anything until the visitor
+    opts in through a CMP, and a decline is honoured for the whole session.
+  A third-party analytics script that loads unconditionally is **non-compliant**.
+- **Display advertising (`#ads`)** always requires a provider-certified CMP and
+  always sets cookies — it is never the privacy-first path. A site that runs ads
+  has a consent banner by necessity.
+- The privacy page renders from the origin manifest (`#third-parties`) — the
+  list of who sees visitor data and why. No hand-written prose enumerating
+  services that goes stale when a dependency changes.
+- Policy pages are a collection; `Last updated` comes from the git commit date,
+  not a hand-typed line.
+- Adding any origin that sees visitor data (an IP in a log counts) is a
+  privacy-page change in the same commit.
+- Native form submissions: state what the handler receives, retention, and link
+  its data-processing terms.
+- If the project sends end-user content to a model provider (`#llm-integration`),
+  the privacy page names the provider and what leaves your origin, and — where
+  the provider offers it — the no-training / zero-retention option is the one in
+  use.
+
+**Verify.** The privacy page's third-party list is generated. Review confirms
+any analytics is privacy-first or gated behind a CMP.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## ads — Display advertising
+
+**Contract.** Display ads are opt-in per project. When present, the ad provider
+is a declared third party (`#third-parties`), loads only after consent through a
+provider-certified CMP (`#privacy`), sits in layout slots with reserved
+dimensions (no layout shift), never loads on a non-production build, and its
+required root files are generated or managed rather than left to drift. The CSP
+relaxation the provider needs is the widest the policy ever gets, scoped to the
+ad directives, and documented.
+
+**Specs.**
+- **Opt-in.** An `ads:` key in the `CLAUDE.md` House-style section — `none`
+  (default) or the provider (e.g. `adsense`). No ad code exists unless recorded.
+- **Consent gate (`#privacy`).** A CMP the ad provider **certifies** is in place
+  (for AdSense: a Google-certified CMP — legally required for EEA / UK /
+  Switzerland traffic). It presents a consent choice *before* the ad loader
+  sets any cookie or identifier, and a decline is honoured (no ads, or
+  non-personalized only where the provider supports it). Whether the prompt
+  shows to every visitor or only to visitors in regulated regions is a project
+  decision recorded in `CLAUDE.md`. What is **non-compliant** regardless: the ad
+  loader firing and setting cookies before the CMP has resolved.
+- **Declared (`#third-parties`).** Every ad-provider origin (loader, ad-serving,
+  ad iframes, the CMP, quality/verification endpoints) is in the origin manifest
+  with `purpose: advertising` and its `dataSeen`. The privacy page renders it
+  like any other entry.
+- **CSP (`#security-headers`).** The provider's origins are added to
+  `script-src`, `frame-src`, `img-src`, and `connect-src` (often `style-src`
+  too — ad code injects styles) in the one header definition, with a comment
+  saying which directives and why. If the provider genuinely needs
+  `'unsafe-inline'` in a script/style directive, it is confined to that
+  directive, recorded as a named exception in the manifest, and shown on the
+  audit page. **Never `'unsafe-eval'`, and never a widened `default-src`.**
+- **No layout shift.** Every ad slot is a container with an explicit reserved
+  size (a `min-height` or `aspect-ratio` matching the unit). An unfilled slot
+  holds its space or is removed cleanly — never left to reflow. This is what
+  keeps `#observability`'s CLS green.
+- **Never on non-production (`#noindex`).** The ad loader and every slot are
+  gated on the same `isProduction` flag as `noindex`. Serving ads on a preview /
+  staging URL wastes impressions, risks an invalid-traffic policy strike, and
+  pollutes analytics.
+- **Root files.** `ads.txt` (and `app-ads.txt` if the account has apps) at the
+  site root, listing authorized sellers, is generated from data or is a reviewed
+  file — not hand-edited over time. Excluded from the sitemap. Treated like
+  `robots.txt`.
+- **Performance & rendering (`#rendering`).** The loader is `async`, runs after
+  first paint, is never render-blocking, and never gates core content. Prefer
+  explicitly placed units over auto-ads / page-level scripts that rewrite the
+  layout.
+- **Editorial** — ad density, placement, and which pages carry ads follow the
+  provider's policies (no ads on error / thank-you / thin pages; a label where a
+  placement could be mistaken for content). Out of code scope, recorded in
+  `CLAUDE.md`.
+
+**Rationale.** Ads are the single largest deviation from this standard's
+defaults — cookies, a CMP, a permissive CSP, cross-origin iframes, and a Core
+Web Vitals cost. Isolating all of it in one contract keeps the rest of the
+standard honest and makes the tradeoff explicit and reviewable.
+
+**Verify.** The audit page has an **Ads** panel (only when `ads:` ≠ `none`):
+`ads.txt` present and parseable; the CMP script present; the CSP grants exactly
+the declared ad origins; any `'unsafe-*'` exception noted; the loader gated on
+`isProduction`. The link/reference check (`#internal-links`) fails on any
+`adsbygoogle` / ad-provider reference in a non-production build and on a missing
+`ads.txt` in the production output. Manually, in a fresh browser on production:
+decline consent → no ad requests in the network panel; accept → ads load; check
+CLS in the browser's own tools.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part H — Links, forms, tests, accessibility
+
+## internal-links — Internal linking
+
+**Contract.** Internal linking is data-driven and validated at build time. A
+dangling internal reference fails the build.
+
+**Specs.**
+- Every content page links **2–4 sibling/related pages**; a page with none is a
+  dead end.
+- Navigation is generated from data, never hand-listed per layout.
+- Cross-links use root-relative paths, never the absolute production URL.
+- A build-time check walks the built output and **exits non-zero** on:
+  - any internal `href` that doesn't resolve to a generated page
+  - any related/glossary slug with no matching content
+  - any referenced asset (`og:image`, preload, `<img src>`, icon) missing from
+    the output
+  - any external `<a>` missing `rel="noopener"` (or `noreferrer`)
+  - any external origin (`href`/`src`/`fetch`/`<script>`) not in the origin
+    manifest
+  - any origin the CSP grants that is not in the origin manifest
+  - any inline `<script>` (without `src`, non-JSON type), inline `<style>`,
+    `on*=` handler, or `style=` attribute in the output — the strict CSP
+    (`#security-headers`, `#styling`) rejects all of these, so a build check is
+    the guard against one creeping back in
+  - any JSON-LD block that doesn't parse or lacks its `@type`'s required fields
+
+**Verify.** The check is part of the gate.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## forms — Forms
+
+**Contract.** Prefer the host platform's native form handling. Every form has
+spam mitigation and meets the client UX/accessibility contract. The handler is
+defined once.
+
+**Specs.**
+- Use the host's native form handling before reaching for a third-party form
+  processor — a processor is a new external origin (`#third-parties`) and a
+  privacy disclosure (`#privacy`).
+- Spam mitigation on every form: an off-screen honeypot field at minimum; add a
+  rate limit / captcha for higher-value targets.
+- Client UX/a11y contract: a validity gate before submit; an `aria-live` status
+  region; the submit button disabled with a busy state while in flight; a real
+  error branch, not only a success path; on success, clear feedback.
+- The submit handler is defined once (a shared script/module), never duplicated
+  per page.
+- Every control has a real associated `<label>`; errors set `aria-invalid` and
+  are announced via `aria-live` referenced by `aria-describedby` (`#a11y`).
+
+**Verify.** Submit a test message end to end after deploy. Review the handler is
+not duplicated.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## domain-tests — Testing domain logic
+
+**Contract.** Anything that computes a result a user relies on is a pure
+function with its own test. The tests encode the rules the page's own copy
+states.
+
+**Specs.**
+- The computation is a pure function in its own module (`#client-logic`), tested
+  with the stack's built-in test runner — no test framework needed for this.
+- **Tests include:**
+  - the worked example from the page's own explanatory copy (they must agree)
+  - boundaries: zero, one, 100%, empty/NaN input, negative input, very large
+    values, floating-point rounding (`0.1 + 0.2`)
+  - every rule the copy states ("rounds up to the next whole cent", "caps at 40
+    hours")
+- For code that calls an external API: the **transform** of the response is a
+  pure tested function with a captured sample response as the fixture; the fetch
+  itself is not unit-tested, but the failure path (timeout / non-200 → fallback
+  state) is; a serverless proxy/endpoint gets its own spec (forwards only the
+  expected fields, returns the fallback shape on upstream failure, never leaks
+  the key).
+- A calc/transform module changed without a matching test change is a review red
+  flag.
+
+**Verify.** The tests are part of the gate.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## a11y — Accessibility checklist
+
+**Contract.** Every page meets the checklist below. An automated a11y scan over
+every page runs in the gate — and is understood to catch regressions, not
+everything.
+
+**Specs.**
+- **Skip link** as the first focusable element, targeting the main landmark,
+  visible on focus.
+- **One `<h1>` per page**; headings in order, no level skipped.
+- **Modals are `<dialog>` + `showModal()`** — native focus trap and inert
+  backdrop. Move focus to the first field on open, restore to the trigger on
+  close; `Escape` closes natively; the close control has an `aria-label`. Don't
+  hand-roll any of it.
+- **`prefers-reduced-motion`:** every transition/animation (reveals, fades,
+  `scroll-behavior`) lives inside `@media (prefers-reduced-motion:
+  no-preference)`.
+- **`<meta name="theme-color">`** with light/dark `media` variants and
+  **`color-scheme: light dark`** on the root, values from `#brand-source`.
+- **Forms:** real `<label for>` on every control; errors set `aria-invalid` and
+  are announced via an `aria-live` region referenced by `aria-describedby`;
+  never signal state by colour alone.
+- **`<details>`/`<summary>`** disclosure widgets: `<summary>` is already a
+  keyboard button — don't re-bind Enter/Space or add `role`/`tabindex`.
+- **Icons:** decorative → `aria-hidden="true"`; meaningful → `<title>` in the
+  SVG or `aria-label` on the control.
+- **Contrast** meets WCAG AA; fix failures at the token (`#brand-source`), not
+  with a one-off override.
+- **Focus visibility:** a visible focus ring on every interactive element; if
+  you override the default, keep one.
+- Before a release that touches interaction, drive the changed flow
+  **keyboard-only and with a screen reader** once.
+
+**Verify.** The automated scan is in the gate. The audit page flags sub-AA
+contrast. The manual keyboard/SR pass is on the change checklist for interaction
+changes.
+
+**Implementation.** See your stack's impl doc, same slug — the impl doc carries
+the scanner mechanism only.
+
+---
+
+# Part I — Gate, CI/CD, secrets, observability
+
+## the-gate — The one check gate
+
+**Contract.** There is exactly one check command that runs everything. Every
+enforcement point runs that same command — never a hand-picked subset.
+
+**Specs.**
+- One gate command runs, ordered cheapest-first: lint/format check → content
+  validation → domain tests → build → link/reference integrity → a11y scan.
+  (Optionally a performance budget once the site has a baseline.)
+- The same command is invoked by: the pre-push git hook, the CI workflow, the
+  deploy script, and the assistant before it reports work complete.
+- There is **no "CI-only" variant** and no partial local run. If the gate
+  passes, the change is shippable.
+- The deploy path re-runs the gate and has **no bypass flag**.
+- Checks that need credentials or inspect production-only state (e.g. the infra
+  doctor) are **not** in the gate — they run at build time for the audit page
+  and as a deploy pre-flight.
+- **Completeness and standard-version drift are checked separately** by
+  `#compliance`, not here. The gate catches *regressions* of contracts already
+  implemented; a chapter that was never implemented, or one the standard added
+  after you adopted it, is a migration gap — not a gate failure.
+
+**Verify.** Grep every enforcement point — each calls the one gate command.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## compliance — Codebase-vs-standard conformance
+
+**Contract.** One command reports the codebase's state against **every chapter**
+of the standard — `PASS` / `FAIL` / `MANUAL` / `N/A` per chapter. It is the
+drift-and-completeness sweep that `#the-gate` (regressions only) does not do,
+and it is **not** part of the gate.
+
+**Specs.**
+- One command walks every CORE chapter and every mirrored impl section and emits
+  one result each:
+  - **`PASS`** — mechanically verified from the repo + the built output.
+  - **`FAIL: <finding>`** — a Contract is violated, or the chapter is
+    unimplemented. The specific finding is printed.
+  - **`MANUAL: <what to check>`** — a judgment the script can't make (e.g. "is
+    the page prose really in the content data, or still in a template?").
+  - **`N/A`** — the chapter doesn't apply given the `CLAUDE.md` keys (`#ads` when
+    `ads: none`; the Part J chapters when `ai: none`, and `#agent-artifacts` /
+    `#usage-metering` unless the `ai:` value opts into them; the `article` half
+    of `#seo-meta` on a `content-type: tool` site).
+- It ends with a summary line: `N pass · M fail · K manual`, then the list.
+- **Not in `#the-gate`.** A `FAIL` is a known migration gap, not a regression —
+  gating on it would freeze all work until the whole migration is done, which
+  contradicts incremental adoption.
+- It runs: **on demand**; **at build time** (cache-aware) feeding the audit
+  page's Compliance panel (`#audit-page`); and the **deploy pre-flight**
+  (`#ci-cd`) **warns** on any chapter that went `PASS → FAIL` since the last
+  deploy (a real regression of something previously compliant).
+- **Standard-version drift is a row.** The command compares the project's pinned
+  `standard-version:` (`#adopting`) to the standard's own version header; if the
+  pin is behind, each `CHANGELOG` slug changed since becomes a
+  `MANUAL: re-check #<slug>` line.
+- The mechanical tier **reuses existing machinery** — the repo-config
+  introspection already in the audit doctor and the built-output scan already in
+  the link/reference check — not a parallel implementation.
+- **When the assistant runs it:** at onboarding (the `FAIL`s *are* the migration
+  backlog); whenever `standard-version:` is behind; before a release that spans
+  several chapters; and whenever asked "are we still in line?".
+
+**Rationale.** The gate catches regressions against contracts you have already
+implemented. It cannot tell you a whole chapter was never done, that the
+standard gained a chapter since you adopted it, or that a `MANUAL`-only contract
+has quietly drifted. This is the systematic "are we still in line" check — the
+counterpart to `#the-gate`.
+
+**Verify.** The audit page's Compliance panel shows the per-chapter grid and the
+summary bar counts non-`PASS` chapters. Rolling the `standard-version` pin back
+by hand lists the intervening `CHANGELOG` slugs as `MANUAL`.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## ci-cd — CI/CD & deploy philosophy
+
+**Contract.** Merging and deploying are decoupled. Production ships through one
+sanctioned, no-bypass command on a deliberate cadence. The default working mode
+is **solo** — one developer, no pull-request ceremony — and the model holds with
+no PRs at all.
+
+**Specs.**
+- A push or merge to the default branch does **not** deploy. Merged work
+  accumulates on `main`.
+- **Committed git hooks**, two tiers, activated by a setup step (not a manual
+  install): a fast pre-commit (lint/format) and a full pre-push (the whole
+  gate). On a solo project these hooks — not code review — are the enforcement
+  point: a failing gate physically blocks the push.
+- **Branching & review — solo is the default.** Work on a short-lived branch for
+  anything non-trivial, let the pre-push hook run the gate, fast-forward `main`,
+  push. Open a **pull request** only for a concrete reason — you want the CI
+  backstop to vet a branch before it reaches `main`, or the rendered diff, or a
+  paper trail — never as self-approval ceremony. A project with more than one
+  committer inverts this: PRs become the norm and carry a second-person review.
+- **Push `main` after each merge** — not for review, for the offsite copy and so
+  the CI backstop actually runs. Never pushing at all is a worse failure than
+  any branching-model choice.
+- A **CI backstop** runs the same gate on every push (and any PR), on a clean
+  machine independent of your laptop — its job is catching an environment
+  difference (fresh install, pinned runtime, no local caches), not gating a
+  merge you already gated locally. Where it cannot be a required status check it
+  is advisory; the pre-push hook and the deploy command are the real
+  enforcement.
+- **Production deploy** is one sanctioned command that: checks it is on `main`,
+  re-runs the gate, builds a production artifact with **your** deploy-target
+  switch set, runs a pre-flight that **hard-fails** on a cost- or SEO-breaking
+  mismatch and **warns** on the rest — including any `#compliance` chapter that
+  went `PASS → FAIL` since the last deploy — then ships. **No `--force`, no
+  `--no-verify`, no env override.**
+- Deploys are deliberate — one deploy batches everything since the last deploy.
+  You own the cadence.
+- Preview builds are non-production and un-indexable (`#noindex`).
+- The deploy-target switch is set by the deploy command, never inferred from a
+  host-injected variable.
+
+**Rationale.** The specific mechanism varies — a static host that bills per build
+wants a pre-built artifact upload with the host's own builds turned off; a
+platform that deploys by `git push` to a release remote is equally fine as long
+as the gate runs first and there is no bypass. The "a push must never trigger a
+build" wording some hosts force is a cost artifact, not the principle. The
+constant is: deploys are gated, sanctioned, and on your schedule.
+
+For a solo developer the whole model holds with **no pull requests**: the
+pre-push hook is the gate, CI is a clean-room second opinion, `bin/deploy` is the
+release. A PR is a tool to reach for when it buys something specific, not a
+required step. Multi-committer projects add the PR-and-review layer on top —
+nothing below it changes.
+
+**Verify.** A push doesn't deploy. The pre-push hook is *installed* (not just
+committed) after the setup step. The deploy command has no skip flag. The audit
+page's infra tab confirms the host isn't auto-building where that costs.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## secrets — Secrets & environment
+
+**Contract.** Secrets are never committed and never reach build output. Each
+context gets the minimum it needs.
+
+**Specs.**
+- **Local:** a git-ignored env file, loaded by the shell or a loader. Commit an
+  `.env.example` with keys and dummy values. Never commit a real one.
+- **CI:** repo secrets, scoped minimally. Deploy credentials are kept separate
+  from any read-only introspection tokens (e.g. the audit doctor's host/CI API
+  tokens).
+- **Runtime:** anything a static page needs at runtime is baked in and therefore
+  public — no secret goes into a data file or template. Server stacks read
+  secrets from the runtime environment only.
+- A **model-provider API key** (`#llm-integration`) is a runtime secret with
+  extra handling: a distinct key per environment, a low provider-side spend cap
+  on the non-prod keys, scoped to the models/endpoints used where the provider
+  supports it, and rotatable without a redeploy.
+- A secret value never surfaces into build output or onto the audit page —
+  presence-as-boolean only.
+- If a secret has been committed historically: purge it from git history and
+  rotate it.
+
+**Verify.** The audit page shows secret **presence** only. A history scan for
+committed secrets is clean.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## observability — Observability & post-launch operations
+
+**Contract.** After launch, the standard operational SEO and performance loop
+runs; production error/APM monitoring is in scope above the static tier.
+
+**Specs.**
+- One-time then occasional (not part of the build, but part of "done"):
+  - verify the production domain in Google Search Console and Bing Webmaster
+    Tools; submit `sitemap.xml` in each
+  - watch Core Web Vitals in Search Console (real-user data, a ranking signal).
+    If the site runs ads (`#ads`), CLS and LCP are the metrics they regress —
+    the reserved ad-slot dimensions are what hold CLS
+  - after a release that adds pages, check indexing coverage a week later
+  - re-run the Rich Results Test after JSON-LD changes; re-check OG rendering
+    after brand or share-image changes
+  - re-run `#compliance` before a release that spans several chapters, and
+    whenever the pinned `standard-version` falls behind — a stale
+    `standard-version` is itself a `MANUAL` row it reports
+- A static site needs no APM. A server/DB application (`#beyond-this-standard`)
+  runs an APM and a health check.
+- If the project calls a model API (`#llm-integration`), per-request token/cost
+  telemetry and a spend-anomaly alert are part of this loop; if it generates
+  artifacts (`#agent-artifacts`) or meters usage (`#usage-metering`), the
+  per-artifact cost figure and the billing-reconciliation drift report join the
+  audit page.
+
+**Verify.** The audit page's manual checklist tracks the search-console /
+sitemap-submission items with `verifiedOn` dates.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part J — AI & agent capabilities (opt-in)
+
+These three chapters apply **only** when a project has the specific need each
+names — the same need-gated opt-in as `#beyond-this-standard` and `#ads`, and
+**not** a consequence of which framework was chosen. A project that calls no
+model-provider API is unaffected: all three are `N/A` (`#compliance`), no
+`CLAUDE.md` key, no code. The triggers are independent — a project may need one
+without the others.
+
+## llm-integration — LLM / agent API integration
+
+**Contract.** In scope the moment the project calls a model provider's API at all
+— chat, completion, embeddings, agentic tool-use, transcription, first-party or
+through a gateway. Every such call is server-side, keyed per environment, bounded
+by an explicit timeout and retry policy, rate-limited on your own side, metered
+for token cost per request, wrapped in a moderation/safety layer sized to the
+subject's risk, disclosed in plain language to end users, and checked against the
+provider's usage policy for the project's subject matter.
+
+**Specs.**
+- **Server-side only.** The provider key is a secret (`#secrets`) read from the
+  runtime environment — never shipped to the browser, never in a data file or
+  build output. The browser calls your endpoint; your endpoint calls the
+  provider. This is the `#third-parties` step-2 rule: a key-bearing call is never
+  client-side.
+- **Key handling per environment (`#secrets`).** A distinct key per environment
+  (dev / staging / prod); a low provider-side spend cap on the non-prod keys;
+  the production key scoped to only the models and endpoints used where the
+  provider supports scoped keys; rotation without a redeploy.
+- **Declared third party (`#third-parties`, `#privacy`).** The provider origin is
+  in the manifest with its `purpose` and a `dataSeen` that states what leaves
+  your origin (user prompt content and any context you attach) and the
+  provider's retention / training posture. Where the provider offers a
+  no-training or zero-retention mode for API traffic, that mode is the one in
+  use. The privacy page renders the entry.
+- **Timeout, retry, rate limits.** Every call has an explicit timeout. Retries
+  use capped exponential backoff with jitter and a maximum attempt count, and
+  cover only the safe-to-retry failures (429, 5xx, connection reset) — never a
+  content, auth, or validation error. A provider `Retry-After` is honoured. The
+  app enforces its **own** per-user / per-session request ceiling independent of
+  the provider's quota, and degrades to a clear message when a ceiling or a
+  timeout is hit — never a hang, never an unbounded queue.
+- **Cost / token observability (`#observability`).** Every call records, per
+  request: model, input tokens, output tokens, computed cost, latency, and
+  outcome (ok / timeout / refusal / error). Token counts come from the provider
+  response where it returns them, not an estimate. The record is queryable by
+  day and by user/session, and a cost anomaly (a spike, a runaway agent loop) is
+  alertable.
+- **Moderation / safety layer, sized to the subject.** Input and output pass a
+  safety check proportional to the domain's risk and the audience:
+  - a low-risk internal or authenticated-staff tool may rely on the provider's
+    built-in safety alone;
+  - a public, unauthenticated, or minor-accessible surface adds an explicit
+    moderation pass (a moderation endpoint, a classifier, or a policy prompt) on
+    user input and on model output, plus prompt-injection mitigation on any
+    tool-calling / agentic path (untrusted retrieved content can never escalate
+    tool permissions or exfiltrate context);
+  - a regulated or high-harm subject (medical, legal, financial guidance) adds
+    the domain disclaimer, explicit scope limits in the system prompt, and a
+    refusal or human-review path for out-of-scope requests.
+  The chosen level and its reasoning are recorded in `CLAUDE.md`.
+- **AI disclosure to end users.** Wherever a user reads model-generated content
+  or converses with a model, a plain, visible statement says so (e.g. "Responses
+  are AI-generated and can be wrong"). Not buried in a policy page. If the model
+  presents as a persona, the disclosure is more prominent, not less.
+- **Provider usage-policy fit.** Before launch, the project's subject matter and
+  intended use are checked against the provider's usage / acceptable-use policy
+  (prohibited-use categories, output-use and attribution terms, any
+  consumer-vs-API distinctions). A mismatch is resolved before shipping. The
+  check is re-run when the subject expands or the provider revises its terms; the
+  date of the last check is on `#observability`'s manual checklist.
+- **The response transform is a pure tested function (`#domain-tests`).** Parsing
+  model output — JSON extraction, tool-call dispatch, citation resolution — is a
+  pure function tested against captured fixtures, along with the timeout,
+  refusal, and malformed-output paths. The network call itself is not
+  unit-tested.
+
+**Rationale.** A model API is simultaneously a third party that sees user
+content, a metered cost centre that can run away, and a source of output that can
+be wrong, unsafe, or against the provider's terms. Each of those needs a
+deliberate control and none of them is the provider's default.
+
+**Verify.** The provider origin is in the manifest and on the privacy page. Grep
+confirms no provider key is reachable from client code. A per-request cost/token
+record exists and the audit page shows spend by day. `CLAUDE.md` records the
+moderation level and the last usage-policy-check date. The disclosure is visible
+on the AI surface in a fresh browser.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## agent-artifacts — Agent-generated downloadable artifacts
+
+**Contract.** In scope only when the project lets a user generate a downloadable
+file through model-driven code execution or an equivalent mechanism (a chart, a
+spreadsheet, a document, an archive). Code execution is sandboxed; artifacts have
+bounded storage with an enforced expiry; delivery is authorization-checked and
+defensively typed; and each artifact carries its own generation cost as an
+observability signal.
+
+**Specs.**
+- **Sandboxed execution.** Model-generated or model-directed code runs in an
+  isolated sandbox with no route to the app's network, secrets, database, or
+  filesystem beyond a scratch directory, and with enforced CPU, memory,
+  wall-clock, and output-size limits. The sandbox is torn down after each run. A
+  shared long-lived interpreter process is not a sandbox.
+- **Storage & expiry.** Artifacts are written to object storage — not the app
+  server's local disk, not the database as blobs. Each has a TTL (a default in
+  hours to a few days, recorded in `CLAUDE.md`) after which a scheduled job
+  deletes it. Total artifact storage per user/session is capped.
+- **Delivery security.** The download route is authorization-checked on every
+  request (the requester owns the artifact or its session) — an unguessable URL
+  is not sufficient unless the artifact is explicitly public and non-sensitive.
+  Responses set `Content-Type` from a server-side allowlist,
+  `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff`, and a
+  restrictive CSP — or are served from an isolated origin — so a generated
+  HTML/SVG file cannot execute in the app's origin. User-influenced filenames are
+  sanitised.
+- **Per-artifact cost (`#observability`).** Each artifact records the model cost
+  and the sandbox compute cost to produce it, attributable to a user/session and
+  queryable alongside the `#llm-integration` per-request figures. A user
+  generating artifacts in a loop is visible and rate-limitable.
+- **Clean degradation.** A sandbox failure, timeout, or oversized result returns
+  a clear error — never a partial or corrupt file, never a hang.
+
+**Rationale.** Executing model-authored code is the highest-privilege thing an AI
+feature does; an unsandboxed run is a remote-code-execution surface. A generated
+file served from the app origin with a guessed content type is a stored-XSS
+surface. Both are opt-in risks that earn their own controls.
+
+**Verify.** Review plus a test confirm a hostile snippet in the sandbox cannot
+reach secrets or the database. A download request without authorization is
+rejected. `Content-Disposition` and `nosniff` are set on artifact responses. The
+expiry job runs and old artifacts are gone. The audit page shows artifact count
+and cost by day.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## usage-metering — Usage-based cost metering
+
+**Contract.** In scope only when the project's pricing is not flat — a per-user
+or per-session allowance, metered overage, or pay-as-you-go tied to AI usage.
+Usage is recorded per subject as an auditable event log, plan-tier limits are
+enforced server-side before the spend is incurred, and the recorded usage is
+reconciled against the payment processor.
+
+**Specs.**
+- **Per-subject event log.** Every metered event (a request, a token batch, an
+  artifact) is written as an immutable row keyed to the user or session, with
+  timestamp, quantity, unit, computed cost, and a link to the originating
+  `#llm-integration` call. Period aggregates are derived from those rows, never
+  kept only as an in-place counter.
+- **Plan-tier enforcement is server-side and pre-spend.** The allowance check
+  runs on your server before the provider call is made — a client-side or
+  after-the-fact check is not enforcement. Over the limit does one of: a hard
+  block with an upgrade path; a metered-overage path the user has explicitly
+  agreed to; or a graceful degrade (a smaller model, a queue) — the choice is
+  recorded in `CLAUDE.md`. Tier limits are read from config/data, not hardcoded
+  across scattered conditionals.
+- **Reconciliation with the payment processor.** A scheduled job compares
+  recorded usage to what the processor (Stripe et al.) was told to bill —
+  metered usage vs. reported usage vs. invoiced amount — and flags drift beyond a
+  threshold for review. Usage reported to the processor is idempotent (a retry
+  never double-bills). Processor webhooks (`subscription.updated`, payment
+  failure) update local tier state.
+- **The user can see their usage.** A usage view shows consumption against the
+  allowance for the current period, computed from the same rows billing uses —
+  not a separate, drift-prone display counter.
+- **Metering survives partial failure.** A provider call that succeeded but whose
+  metering write failed is reconciled (the usage is not lost); a metering write
+  for a call that then failed is reversed or netted. Both paths are tested.
+- **Boundaries are pure tested functions (`#domain-tests`).** At the limit, one
+  over, a tier change mid-period, proration, and a refund are each covered.
+
+**Rationale.** Usage-based pricing puts a correctness-critical number — what the
+user owes — on the same path as a flaky external call. Without an auditable
+per-event log and processor reconciliation, billing silently drifts from reality
+and neither side can tell.
+
+**Verify.** Usage rows exist per event and the aggregates reconcile to them. A
+request over the tier limit is blocked or metered server-side — tested. The
+reconciliation job runs and its drift report is on the audit page. The
+user-facing usage figure matches the billing record.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+---
+
+# Part K — Meta
+
+## generated-asset-freshness — Keeping generated assets fresh
+
+**Contract.** A generated asset (OG card, favicon, tokens stylesheet) cannot be
+allowed to go stale. Regeneration is layered so no single tier is a
+single point of failure.
+
+**Specs.**
+1. **A build step that always runs** regenerates on every build and every
+   incremental rebuild. If a build ran, the assets are correct.
+2. **An editor/agent hook** regenerates the moment a source-of-truth file
+   (`#brand-source` and its inputs) is edited, even with no dev server running,
+   and nudges the operator to review the audit page.
+3. **A `CLAUDE.md` instruction** covers the judgment cases the hook's
+   path-matching can't (e.g. a page-title edit), and tells the assistant to run
+   the one gate before reporting work complete.
+- The Claude Code `PostToolUse` hook **pattern** is the same on every stack —
+  match an edit to a source-of-truth file, run the regen command, surface a
+  message. Only the command and the watched-file globs are per-stack.
+- `CLAUDE.md` states the `#brand-source` single-source rule so the assistant
+  never hardcodes a brand value.
+
+**Verify.** Edit a brand token with no server running → the hook regenerates and
+the audit page reflects it after a rebuild.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## beyond-this-standard — Beyond this standard
+
+**Contract.** This standard covers content sites, tool sites, and their forms.
+When a project needs more, that is a deliberate threshold crossing, not a drift.
+
+**Specs.**
+- **Signals you are past the static envelope:** a database; user accounts /
+  authentication; server-side application logic; server-side rendering per
+  request; per-user state; background jobs; bolting a datastore (e.g. "Netlify
+  DB") onto a static stack.
+- **An LLM / agent surface** is its own opt-in axis (Part J), gated by need, not
+  by framework. A single stateless model call from an otherwise-static site is a
+  serverless function (`#third-parties`); server-managed conversations,
+  streaming, code-execution artifacts, or usage metering put you past the
+  envelope. Either way the controls are `#llm-integration` and its siblings.
+- **What carries over unchanged:** SEO (`seo-*`, `structured-data`,
+  `sitemap-robots`, `noindex`), `a11y`, `domain-tests`, `the-gate`, `ci-cd`
+  philosophy, `secrets`, `brand-source`, `content-model`'s validation contract,
+  `privacy` posture, `security-headers`, `observability`.
+- **What changes:** the deploy model (a running server, migrations), the content
+  model (DB-backed content joins externalized files), and rendering (SSR is
+  native, not a prerender workaround).
+- If the "yes" is substantial, the right framework is probably **Elixir/Phoenix**
+  — `stacks/phoenix.md` is the binding of this standard for when a database is in
+  scope. A small "we need one dynamic thing" is often better served by a single
+  serverless function (`#third-parties`) than by changing frameworks.
+
+**Verify.** The project's `CLAUDE.md` `scope:` key records `static+forms` or
+`+db` / `+auth` / `+ssr`.
+
+**Implementation.** For `+db` and beyond, use `stacks/phoenix.md`.
+
+## adopting — Adopting this standard
+
+**Contract.** Every project runs the stack-selection flow at the start and
+records the result. "The gate passing" is the definition of compliant.
+
+**Specs.**
+
+**Stack-selection flow** — run at project start (or when onboarding an existing
+project), before non-trivial work. Ask five questions with defaults:
+
+1. **Framework?** Eleventy + Netlify *(default)* · Elixir/Phoenix *(when a
+   database or server-side state is in scope — `#beyond-this-standard`)* · other
+   *(→ no binding exists; use this file as principles and do what is idiomatic
+   for the technology)*. `stacks/sveltekit.md` is a **parked** stub — its
+   friction points and open questions are written, the per-section "how" is not;
+   it is not on offer here until a real project forces those decisions, so
+   treat SvelteKit as "other" for now.
+2. **CSS system?** Pico classless *(default)* · Pico class-based · Tailwind ·
+   Tailwind + component library · vanilla tokens. (Options are bound per stack
+   in the impl doc's `styling` section.)
+3. **Anything outside "static + forms"?** — a database, auth, server-side logic,
+   SSR, background jobs, per-user state. *Default: No.* Yes →
+   `#beyond-this-standard`; a substantial yes → revisit Q1 (probably Phoenix).
+4. **Display advertising?** *Default: No.* Yes → `#ads`; record `ads: <provider>`
+   (e.g. `adsense`). This brings a consent banner, a widened CSP, an `ads.txt`,
+   and a CWV cost — it is a deliberate choice, not a default.
+5. **Does the project call an LLM / agent API?** *Default: No.* Yes → Part J;
+   record `ai: llm-api`. Then two independent follow-ups: does a user generate
+   downloadable files via model-driven code execution? (→ add `+artifacts`,
+   `#agent-artifacts`); is pricing usage-based rather than flat? (→ add
+   `+metering`, `#usage-metering`). This gate is by real need, not by framework —
+   a plain CRUD app that calls no model is unaffected.
+
+Follow-ups when relevant: production domain; content type (`tool` vs `article` —
+`article` implies feeds); publishing rate for content sites.
+
+**Starting point.** Where a copy-and-modify template exists for the chosen stack
+(`templates/<stack>/` — see the impl doc and `README.md`), starting from it *is*
+the new-project path: the template is already compliant, so a new project begins
+at "fill in brand + content" instead of "assemble the machinery". The impl doc's
+numbered new-project checklist is then two things: the by-hand equivalent for a
+stack with no template, and the annotated inventory of what the template
+contains. Only `eleventy-netlify` has a template today; the others follow the
+checklist. The recommended input to the flow is a filled
+`templates/concept-brief.md` (the idea, the answers above, a concept-level
+brand, the content model, layout notes) — `README.md` has the hand-off.
+
+**Record** the result near the top of the project's `.claude/CLAUDE.md` /
+`AGENTS.md` as a `## House style` section — a directive paragraph plus a data
+block. The recommended text:
+
+```markdown
+## House style
+
+This project follows the web house style at <path or repo>. **Use it for all
+work unless a request explicitly says otherwise.** Before implementing
+anything, check whether a chapter in `core.md` or `stacks/<framework>.md`
+governs it and follow that chapter — the slugs are the index (a `<script>` →
+`#security-headers` + `#client-logic`; a new page → `#seo-meta` +
+`#internal-links`; anything brand → `#brand-source`; a third party →
+`#third-parties`).
+
+- A conflict between the current code and a chapter is a **migration gap** —
+  surface it; don't quietly fix it inside an unrelated task and don't quietly
+  route around it.
+- Never silently diverge from a **Contract**. A deliberate deviation is
+  recorded in this section with its reason.
+- Where the house style is silent, do what is idiomatic for the stack.
+- Run the gate (`<stack check command>`) before reporting any change complete —
+  a green gate is the definition of done.
+- Run `<stack compliance command>` (`#compliance`) at onboarding — its `FAIL`s
+  are the migration backlog — and again whenever `standard-version` is behind
+  the standard's current version.
+
+- framework: eleventy-netlify
+- css: pico-classless
+- scope: static+forms          # or: +db, +auth, +ssr — see core.md#beyond-this-standard
+- ads: none                    # or: adsense — see core.md#ads
+- ai: none                     # or: llm-api  (+artifacts if model-driven file downloads, +metering if usage-priced) — see core.md#llm-integration
+- production-url: https://example.com
+- content-type: tool           # tool | article  (article => feeds)
+- publishing-rate: ~5 pages/week
+- standard-version: 2026-09-01  # optional pin
+```
+
+If the section is absent, the assistant's first action is to run the flow above
+and propose it. Each impl doc's `adopting` section fills in the gate command and
+adds any stack-specific `CLAUDE.md` prose (e.g. the generated-assets note).
+
+**Onboarding an existing project** — after recording the section, run
+`#compliance`. Every `FAIL` and `MANUAL` becomes a migration-backlog item,
+worked incrementally (the impl doc's migration path is the ordered version of
+that backlog). The project is not expected to be all-`PASS` on day one; it is
+expected to know exactly where it isn't.
+
+**Change checklist (stack-agnostic)** — run before merging to `main`, and again
+before `bin/deploy`. (On a multi-committer project this is also the PR-review
+checklist.)
+- the gate is green locally (and in CI once pushed); the audit page summary bar
+  is clean
+- new/changed content is in data, not markup; the schema is updated; `title` +
+  `meta_description` present and in range
+- a new page has 2–4 related links, resolves an `og:image`, is in a collection
+  or deliberately excluded, has a directory-style permalink
+- a touched formula has a pure module + a test encoding the page's worked example
+- a touched brand token / stylesheet / card template / icon generator has had
+  the audit page reviewed
+- an added external origin passed the decision test, is in the manifest, the CSP
+  is widened to match, the failure/no-JS fallback is tested, the privacy page is
+  updated — all in the same change
+- a changed permalink ships a `301`
+- new interactive UI: keyboard + reduced-motion + labels
+- a changed dashboard setting bumped its `verifiedOn`
+- if a migration-backlog item was the point of the change, `#compliance` now
+  reports it `PASS` (or `MANUAL` with a note)
+- commit messages follow convention; the change is one logical unit
+
+Each impl doc adds a concrete new-project checklist and an ordered, dependency-
+aware migration path.
+
+**Verify.** The `CLAUDE.md` `## House style` section exists (the directive
+paragraph *and* the data block) and is loaded each session.
+
+**Implementation.** See your stack's impl doc, same slug.
+
+## out-of-scope — Cross-cutting out of scope
+
+Named so they are a conscious "not now", not an oversight. Add coverage when a
+project actually needs it.
+
+- **Internationalization** — multiple locales, `hreflang`, per-locale sitemaps.
+  Revisit URL and canonical strategy if added.
+- **Analytics beyond privacy-first or consent-gated** — out by **policy**
+  (`#privacy`), not merely scope.
+- **Ad-density and editorial ad policy** — `#ads` covers the wiring (consent,
+  CSP, CLS, `ads.txt`, non-prod gating); how many units per page, where they go,
+  and which pages carry them is the provider's policy plus editorial judgment,
+  recorded in `CLAUDE.md`, not specified here.
+- **A design-token pipeline** (Style Dictionary et al.) — `#brand-source` as one
+  file is the small-project version; graduate only when tokens outgrow it.
+- **Server-side application logic as a way to run the app** — that is
+  `#beyond-this-standard`; a thin key-hiding proxy is the one carve-out
+  (`#third-parties`).
+- **ML infrastructure** — model fine-tuning or training pipelines, a
+  vector-store / RAG retrieval layer, an evals harness, a prompt-versioning
+  system. `#llm-integration` covers *calling* a model API; building the
+  machinery around it is its own design per project.
+
+Each impl doc keeps its own stack-specific out-of-scope list.
+
+## anti-patterns — Stack-agnostic anti-patterns
+
+- A brand colour / font / logo hardcoded outside the brand source.
+- Content strings living in markup when they're really data.
+- A committed `.env`; a secret in a data file or template.
+- Hand-maintained `sitemap.xml` / `robots.txt` / `feed.xml`.
+- Any third-party analytics that loads before consent; GA/GTM without a CMP
+  gate; analytics that sets a cross-site cookie.
+- An ad loader that runs before consent; ads on a non-production build; a
+  hand-edited `ads.txt` left to drift; an ad slot with no reserved dimensions
+  (CLS); a CMP the ad provider doesn't certify; auto-ads that rewrite page
+  layout; `'unsafe-eval'` or a widened `default-src` added to satisfy an ad
+  script.
+- A model-provider API key in client code or a data file; an LLM call made from
+  the browser.
+- An LLM feature with no per-request token/cost record, no app-side per-user
+  request ceiling, or unbounded agent retries — a runaway-cost surface.
+- Model-generated code executed outside a sandbox; a generated file served from
+  the app's own origin with a guessed `Content-Type` and no `attachment`
+  disposition.
+- AI-generated content shown to users with no visible disclosure that it is AI.
+- Shipping an AI feature without checking the provider's usage policy against the
+  project's subject matter.
+- Usage-based billing with no auditable per-event log, or plan limits enforced
+  only client-side or after the spend; usage reported to the payment processor
+  non-idempotently.
+- A content page with no related links (a dead end).
+- Re-implementing what native `<dialog>` / `<summary>` already do.
+- Transitions/animations not gated behind `prefers-reduced-motion`.
+- Treating the automated a11y scan as full accessibility coverage.
+- Canonical / OG / sitemap URLs that vary by deploy context, or are relative.
+- An `og:image` that is relative, a `data:` URI, an SVG, hotlinked, or absent.
+- OG / meta tags hand-written per page instead of one data-driven implementation.
+- An inline `<script>`, `on*=` handler, or `style=` attribute in the output —
+  the strict CSP blocks all of them; the wiring belongs in a loaded file.
+- A custom web font shipped without checking its subset covers the site's text.
+- A third `PROJECT.md`-style rules doc.
+- CI or a git hook running a hand-picked subset of the gate.
+- Putting `#compliance` in the gate (a migration gap would then block all work),
+  or treating one of its `FAIL`s as a regression to fix immediately rather than
+  a backlog item.
+- Working through a migration backlog without re-running `#compliance`, so it's
+  unknown what's actually left or what regressed.
+- A `standard-version` pin left behind the standard's current version with no
+  `CHANGELOG`-delta re-check.
+- A permalink changed with no `301` from the old path.
+- A default branch other than `main`.
+- Deploying by pushing to a branch instead of the sanctioned gated command.
+- An `immutable` cache header on an asset whose filename isn't content-hashed.
+- Relying on the assistant to *remember* to regenerate assets instead of a hook.
+- More than one file reading environment variables for the site.
+- An audit page with no summary bar, a secret value on it, or a client-side
+  password treated as access control.
+
+---
+
+# Appendix — Slug registry
+
+The canonical set of CORE slugs. An impl doc reuses a slug **only** for the
+mirrored chapter; impl-only chapters take slugs that appear nowhere here.
+
+`repo-hygiene` · `runtime-pin` · `config-idiom` · `content-model` · `rendering` ·
+`assets` · `styling` · `client-logic` · `theme` · `seo-urls` · `seo-meta` ·
+`og-image` · `structured-data` · `sitemap-robots` · `noindex` · `brand-source` ·
+`audit-page` · `security-headers` · `caching` · `third-parties` · `privacy` ·
+`ads` · `internal-links` · `forms` · `domain-tests` · `a11y` · `the-gate` · `compliance` ·
+`ci-cd` · `secrets` · `observability` · `llm-integration` · `agent-artifacts` ·
+`usage-metering` · `generated-asset-freshness` · `beyond-this-standard` ·
+`adopting` · `out-of-scope` · `anti-patterns`
+
+**Shared-concept drift guard** — defined only here; an impl doc may state the
+*how*, never restate the *what*: `the-gate`, `ci-cd`, `third-parties`,
+`brand-source`, `noindex`, `content-model`, `beyond-this-standard`.