bsmnt 0.12.0 → 0.13.0

package/src/agent-skills/ketch-consent-setup/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: ketch-consent-setup
+description: >-
+  Install the Ketch consent gate (CMP) in a basement Next.js project, and control
+  its UI — env vars, the Smart Tag, the consent store, where preferences are
+  reachable from, and styling. Use when the user asks to "add Ketch", "install
+  Ketch", "set up the cookie banner", "set up the consent banner", "add a CMP",
+  "add the consent gate", "we need cookie consent". Also use for UI questions
+  about an existing Ketch install: "hide the floating cookie button", "move the
+  consent widget out of the corner / into the footer", "restyle the consent
+  banner", "pass custom styles to Ketch", "make the banner match our design
+  tokens", or "why isn't the consent banner showing". Gating an individual
+  tracker is the `ketch-consent-check` skill.
+---
+
+# Install the Ketch consent gate
+
+Ketch is the CMP. It owns the consent record, the jurisdiction resolution, the
+legal copy, the banner and preferences modal, and the persistence. The project
+owns exactly three things, and this skill wires all three:
+
+1. Loading Ketch's Smart Tag.
+2. **One** helper that answers "do I have consent for category X?".
+3. An entry point to reopen preferences after the banner is gone.
+
+**Already installed?** If `lib/integrations/ketch/` exists, stop — you want the
+`ketch-consent-check` skill instead, which gates an individual tracker.
+
+Read each file first and adapt to its actual shape — do not blindly
+pattern-match. If an anchor below is missing, stop and report it rather than
+guessing.
+
+## 0. Preconditions
+
+- A basement Next.js project (App Router).
+- A Ketch account for the client, with a **property** already created. You need
+  its org code and property code. If the property doesn't exist yet, that's a
+  dashboard task at https://app.ketch.com and it blocks this skill — report it.
+- If you intend to hide Ketch's floating button, a persistent surface every
+  template renders — footer, nav, settings menu (in a basement project usually
+  `components/layout/footer` reached via `components/layout/wrapper`).
+
+## 1. Env vars
+
+Both codes are public — they appear in the boot URL in the page source — so
+they go in as plain values:
+
+```bash
+bun run env:set NEXT_PUBLIC_KETCH_ORG_CODE <org_code> --plain
+bun run env:set NEXT_PUBLIC_KETCH_PROPERTY_CODE <property_code> --plain
+```
+
+Get them from 1Password → **Development** vault → the project's integrations
+item. They are the two path segments of the boot URL:
+
+```
+https://global.ketchcdn.com/web/v3/config/<org>/<property>/boot.js
+```
+
+If all you have is the raw Ketch `<script>` snippet, read both out of that URL.
+
+Because they are plain, **nothing needs to be pushed to Vercel** — the build
+reads the committed `.env` and Next inlines them. Do not run
+`env:setup-remote` for these.
+
+Document them in `.env.example` too.
+
+## 2. Files — `lib/integrations/ketch/`
+
+Follow the shape of the project's other integrations (e.g.
+`lib/integrations/hubspot/`): self-contained folder, relative imports inside it,
+`@/` imports across folders, and a `README.md`.
+
+| File | Role |
+| --- | --- |
+| `env.ts` | Validates both codes against `/^[a-z0-9_-]+$/i`, exports `ketchBootUrl` (`null` when unset) |
+| `types.ts` | Types for the `window.ketch` / `window.semaphore` surface |
+| `categories.ts` | Category ↔ Ketch purpose ↔ tracker mapping |
+| `consent-store.ts` | The only module that talks to Ketch |
+| `use-consent.ts` | The helper everything else imports |
+| `script.tsx` | Renders the Smart Tag |
+| `preferences-button.tsx` | Preferences entry point (`cva`, takes `variant` / `size`) |
+| `ketch-experience.css` | Maps Ketch's theme to the project's tokens |
+
+### 2.1 Categories
+
+Three stable local names so nothing else hardcodes a Ketch purpose code:
+
+```ts
+export const CONSENT_CATEGORIES = {
+  essential: "essential_services",
+  analytics: "analytics",
+  marketing: "targeted_advertising",
+} as const
+```
+
+Confirm the right-hand side against the property's real purpose codes:
+
+```bash
+curl -s https://global.ketchcdn.com/web/v3/config/<org>/<property>/production/default/en/config.json \
+  | jq -r '.purposes[] | "\(.code)  \(.name)"'
+```
+
+### 2.2 The store
+
+Module-level state read through `useSyncExternalStore` — no Provider, no
+Context. It attaches `ketch('on', 'consent')` and `ketch('on', 'jurisdiction')`
+once, on first subscribe, and re-notifies subscribers on every preference
+change. `useConsent()` wraps it and exposes `hasConsent(category)`, `granted`,
+`isResolved`, `jurisdiction` and `openPreferences()`.
+
+Three facts about Ketch's runtime that the store has to respect:
+
+- Consent arrives as `Record<purposeCode, boolean>`, and a purpose key is
+  **absent** until a record exists. **Absent must read as denied** — this is
+  what guarantees nothing fires before consent.
+- `window.ketch(cmd, …)` pushes onto `window.semaphore`, and Ketch's `boot.js`
+  **unshifts** its own `["init", config]` entry. So queuing commands before the
+  SDK loads is safe; after init, `semaphore.push` is rebound to dispatch
+  directly and `semaphore.loaded` flips to `true`.
+- Persistence is Ketch's, not ours: `_ketch_consent_v1_` in `localStorage` plus
+  the `_swb` cookie, surviving navigation and reloads. **Do not add a second
+  source of truth** — they drift.
+
+### 2.3 knip
+
+Register the folder as an entry or CI fails on "unused exports":
+
+```jsonc
+// knip.json
+"entry": ["lib/integrations/ketch/**/*.{ts,tsx}", /* …existing… */]
+```
+
+## 3. Load the tag
+
+```tsx
+export const KetchConsentScript = () => {
+  if (!ketchBootUrl) return null
+  return <script async src={ketchBootUrl} />
+}
+```
+
+**Mount it in the layout that renders the site chrome, not the root layout.**
+In a basement project that is the route group holding the header and footer —
+`app/(content)/layout.tsx` — alongside the entry point from step 4b:
+
+```tsx
+const Layout = ({ children }: { children: React.ReactNode }) => (
+  <>
+    <KetchConsentScript />
+    <Wrapper>{children}</Wrapper>
+  </>
+)
+```
+
+The root layout also wraps admin routes like `/studio`, and a CMP has no
+business loading there: nothing on those routes tracks anyone, the banner
+covers the tooling, and the floating button lands on top of the Studio UI.
+Mounting one level down keeps Ketch on the pages that actually need it.
+
+Two consequences worth knowing, neither of them a problem:
+
+- `script.tsx` imports `ketch-experience.css`, so the styles ride along with
+  the component and only ship on the routes that render it. That is what you
+  want — it also means the floating-button override is scoped the same way.
+- Ketch does not load on the 404, which falls back to the root layout. Fine as
+  long as nothing tracks there either. If you later mount a tracker in the root
+  layout, move this back up and accept it on `/studio`.
+
+Three traps, all verified on Next 16.3 + React 19:
+
+- **Do not use `next/script` with `strategy="beforeInteractive"`.** It throws
+  *"Encountered a script tag while rendering React component"* and emits no
+  server-side `<script>`. A plain `<script async src>` is hoisted into `<head>`
+  by React 19 during SSR, which is what a CMP needs.
+- **Do not render it as a sibling of `<body>`.** A `<script>` as a direct child
+  of `<html>` is invalid HTML and produces a cascade of hydration errors. If
+  you do mount it in the root layout, it goes *inside* `<body>`.
+- **Do not mount it in a layout that some templates skip.** Consent has to be
+  askable on every page a visitor can land on. One layout above the footer, not
+  per-page.
+
+When `ketchBootUrl` is `null` the tag is not rendered and every consent check
+returns `false` — the site degrades to "no tracking", never to "tracking
+without consent".
+
+## 4. Decide the UI — do not assume
+
+Ketch ships a banner, a preferences modal and a floating button, all in **light
+DOM**, so the project can keep, restyle, reposition or hide any of it. There is
+no single correct answer here — **ask, or follow the design.** Do not copy
+another project's choice.
+
+Two decisions:
+
+**a. The floating button.** Ketch mounts it into `<div id="lanyard_fab_button">`
+as `body.firstChild` whenever the property config has an `accessibilityButton`.
+
+| Option | When |
+| --- | --- |
+| Keep it as configured | No design opinion yet; fastest path |
+| Reposition / restyle it | It collides with a chat widget or sticky CTA |
+| Hide it | The design forbids persistent floating UI (common — it covers the layout on every page and is worst on mobile) |
+
+**b. Where preferences are reachable from.** Consent must stay reopenable after
+the banner is gone. The floating button, a footer link, a nav item, a
+privacy-page link, or several — all valid. If you hide the floating button you
+**must** provide another entry point, and it has to be on something every
+template renders.
+
+Whatever the project picks, route the call through the integration's helper
+(`openPreferences()`), not `window.ketch` directly.
+
+Mechanisms for all of the above — the exact element IDs, why hiding the button
+needs `!important`, the available `ketch(…)` commands — are in
+[`references/ui-customization.md`](references/ui-customization.md).
+
+## 5. Styling
+
+Ketch's UI is styleable three ways, and they compose. Choose by how much design
+control is needed and whether you have dashboard access:
+
+| Approach | Trade-off |
+| --- | --- |
+| **Dashboard theme** | Survives code changes, no CSS to maintain — but hexes are duplicated from the design system and drift |
+| **`--k-*` variable overrides** | Token-driven, so the design system stays the source of truth and Ketch follows automatically — but the names are Ketch-internal |
+| **Direct CSS on Ketch's element IDs** | Total control, needed for layout and responsive work — but couples to Ketch's DOM |
+
+Default recommendation for a basement project: **variables for colour and type,
+direct CSS only for structure.** That keeps the banner following the design
+tokens with no maintenance, e.g.:
+
+```css
+html:root {
+  --k-banner-container-background-color: var(--color-primary);
+  --k-banner-header-title-color: var(--color-secondary);
+  --k-banner-description-link-color: var(--color-contrast);
+}
+```
+
+Scope overrides to `html:root`, **not** `:root` — Ketch injects its own `:root`
+block into `<head>` at runtime, after the project stylesheet.
+
+If there is no design yet, wire it to whatever tokens exist rather than
+hardcoding hexes; the UI then updates on its own when real tokens land. Say so
+explicitly instead of inventing a visual direction.
+
+Variable naming, how to enumerate what a property exposes, the `!important`
+rules, mobile and safe-area handling, and the case for replacing the UI entirely:
+[`references/ui-customization.md`](references/ui-customization.md).
+
+## 6. Verify
+
+```bash
+bun run typecheck && bun run lint && bun run knip && bun run build
+```
+
+Then in the browser:
+
+1. Load a page that renders your chosen entry point. **In a Sanity
+   page-builder project `/` is usually a 404** — no page document exists for
+   it — and the 404 falls back to the root layout, so it has no chrome and no
+   Ketch. Testing there shows no banner and no button and looks broken. Use a
+   real slug.
+2. The tag is in `<head>`:
+   `curl -s <url> | grep -o '<script async[^>]*ketchcdn[^>]*>'`
+   If it only appears escaped inside the RSC payload (`\"src\":\"https://…`)
+   and not as a real tag, you are looking at a 404, not a page.
+3. `window.semaphore.loaded === true` in the console.
+4. The banner shows on first visit, and the chosen entry point reopens the
+   preferences modal.
+5. The floating button is in the state you intended — kept, moved or hidden —
+   both while the banner is open and after it's dismissed.
+6. Check at <640px too; a widget that looks fine on desktop can cover the
+   layout on mobile.
+7. Choose something, reload, confirm it persisted.
+
+## 7. Region behaviour — confirm and document it
+
+Ketch resolves a jurisdiction from the visitor's IP and applies that
+jurisdiction's legal basis per purpose. This is dashboard configuration, not
+code, so **read it rather than assuming**:
+
+```bash
+for j in gdpr US_California US_Texas Canada Quebec default; do
+  echo "== $j"
+  curl -s https://global.ketchcdn.com/web/v3/config/<org>/<property>/production/$j/en/config.json \
+    | jq -r '[.regulations[0]] + [.purposes[] | "\(.code)=\(.legalBasisCode)"] | join("  ")'
+done
+```
+
+Typical result: EEA/UK/CH, California and Quebec are **opt-in**
+(`consent_optin` — off until accepted); Canada and most US state-privacy-law
+states are **opt-out** (`consent_optout` — on until refused); everywhere else
+falls to `default` (`disclosure`, notice only). The full jurisdiction → region
+map is in the property's `boot.js` under `jurisdiction.scopes`.
+
+Put the resulting table in the integration's `README.md` — "what an EU visitor
+sees vs a US visitor" is a question that gets asked repeatedly.
+
+Note that because the helper defaults to denied until Ketch confirms, the
+project's own trackers stay off in opt-out regions too until the record
+arrives. That is stricter than required and intentional.
+
+**Opt-out and notice-only jurisdictions won't show Accept/Reject, and the
+banner won't come back on reload** once Ketch auto-grants that jurisdiction's
+default record — that's the legal basis, not a bug. To actually see and test
+the opt-in banner, force a jurisdiction that has one — append
+`?ketch_jurisdiction=gdpr` (or `US_Texas`, …) to the URL, no code change
+needed. Full mechanics, including a code-level override for previews, are in
+`references/ui-customization.md`.
+
+## 8. Document it
+
+Document it wherever the project already documents integrations — a section in
+the root `README.md`, or a `lib/integrations/ketch/README.md` if the project uses
+per-integration READMEs. Ask rather than adding a file nobody wanted.
+
+Cover: what Ketch is, who owns the account, where the keys live, **how another
+integration checks consent before firing**, the region-by-region behaviour, and
+open dashboard items.
+
+## Next
+
+Gating an actual tracker (GTM, PostHog, Claydar, …) is the
+`ketch-consent-check` skill. Do not wire trackers here.

package/src/agent-skills/ketch-consent-setup/references/ui-customization.md

@@ -0,0 +1,329 @@
+# Controlling Ketch's UI
+
+Ketch ships its own banner, modal, preferences center and floating button. This
+file documents the surface it exposes so a project can keep, restyle, reposition
+or replace any of it. **None of these choices is "the" right one** — pick per
+project and per design.
+
+## What Ketch actually renders
+
+All of it is **light DOM — there is no shadow root**, so ordinary CSS reaches it.
+
+| Element | What it is |
+| --- | --- |
+| `<div id="lanyard_root">` | Host for every experience: banner, modal, preferences, consent gate |
+| `<div id="lanyard_fab_button">` | The floating button. Inserted as **`body.firstChild`** |
+| `#ketch-banner` | The banner container |
+| `#ketch-banner-content` | Banner copy area |
+| `#ketch-banner-buttons-container-standard` / `-compact` | Banner button rows (which one depends on the configured size) |
+| `#ketch-banner-button-*` | Individual banner buttons |
+| `#ketch-modal` | The "customize settings" modal |
+| `#ketch-preferences` | The preferences center |
+| `#ketch-preferences-purposes-tab`, `-subscriptions-tab`, `-requests-tab`, … | Preference center tabs |
+
+At runtime Ketch also appends a `<style>` to `<head>` containing
+`:root { --k-…: …; }` with its whole resolved theme. **That stylesheet lands
+after the project's CSS** — the single most important fact for overriding it.
+
+The floating button is only rendered when both are true:
+
+- the property config has an `accessibilityButton` object, and
+- experiences aren't disabled.
+
+So removing `accessibilityButton` in the Ketch dashboard is the only way to stop
+it being created at all. Everything below is client-side.
+
+## Choice 1 — the floating button
+
+### Keep it (Ketch's default)
+
+Do nothing. Position and colour come from `accessibilityButton` in the
+dashboard (`position: "bottom-left" | "bottom-right" | …`, `color`). Change it
+there, no code.
+
+### Reposition or restyle it
+
+```css
+#lanyard_fab_button {
+  inset: auto 1.5rem 1.5rem auto;
+  z-index: 40;
+}
+```
+
+Useful when the dashboard's corner collides with a chat widget or a sticky CTA.
+
+### Hide it
+
+```css
+#lanyard_fab_button {
+  display: none !important;
+}
+```
+
+`!important` is **required**: Ketch toggles this element's inline
+`style.display` when experiences open and close, and an inline style beats any
+plain rule. Without it the button reappears after the banner is dismissed.
+
+If the project's linter forbids `!important`, scope an override rather than
+dropping it — the rule doesn't work without it:
+
+```jsonc
+// biome.json → overrides
+{
+  "includes": ["lib/integrations/ketch/ketch-experience.css"],
+  "linter": { "rules": { "complexity": { "noImportantStyles": "off" } } }
+}
+```
+
+Hiding it in CSS is a patch: Ketch still mounts the element on every page.
+Removing `accessibilityButton` from the dashboard is the durable fix. Do both
+when you have dashboard access; flag it as a follow-up when you don't.
+
+## Choice 2 — where preferences are reachable from
+
+Consent has to stay reopenable after the banner is gone. Any of these works:
+
+| Option | How |
+| --- | --- |
+| Ketch's floating button | Default, nothing to build |
+| A footer link | Render a button that calls `openPreferences()` |
+| A nav / settings menu item | Same call, different mount point |
+| A privacy-policy page link | Same call |
+| Several at once | Fine — the call is idempotent |
+
+The integration's `openPreferences()` helper opens the preferences center as a
+**modal** over the current page, not a full-page navigation:
+
+```ts
+window.ketch("showConsent", { displayHint: "experiences.consent.modal" })
+```
+
+Prefer routing it through the integration's helper (`openPreferences()` from
+`useConsent()`) so nothing else touches `window.ketch`.
+
+It is safe to call before the SDK has loaded — it queues on `window.semaphore`
+and dispatches after init — so a control doesn't need to wait for readiness or
+be disabled on first paint.
+
+Related commands:
+
+| Command | Effect |
+| --- | --- |
+| `ketch("showConsent", { displayHint: "experiences.consent.modal" })` | Open preferences as a modal — what `openPreferences()` calls |
+| `ketch("showPreferences")` | Open the full-page preference experience instead of a modal |
+| `ketch("showConsent")` | Re-show the consent banner |
+| `ketch("showPreferences", { tab: "purposes" })` | Open the full-page experience on a specific tab |
+
+Whichever mount point you choose, put it somewhere **every template renders** —
+usually the footer or a persistent nav — and verify it on a route that isn't the
+homepage.
+
+## Choice 3 — styling
+
+Three approaches. They compose; pick by how much design control the project
+needs and whether you have dashboard access.
+
+### A. Theme it in the Ketch dashboard
+
+Set colours, radii and fonts in the property's theme editor.
+
+- **For:** survives any code change, no CSS to maintain, works for teams
+  without frontend access.
+- **Against:** hex values duplicated from the design system, so it drifts when
+  tokens change; needs dashboard access; can't reference CSS variables.
+
+Best when the site's palette is stable and nobody wants Ketch CSS in the repo.
+
+### B. Override the `--k-*` variables (token-driven)
+
+Ketch's components consume their theme through CSS custom properties, so
+redefining them restyles the UI without touching structure:
+
+```css
+html:root {
+  --k-banner-container-background-color: var(--color-primary);
+  --k-banner-header-title-color: var(--color-secondary);
+  --k-banner-description-link-color: var(--color-contrast);
+  --k-banner-buttons-primary-background-color: var(--color-secondary);
+  --k-banner-buttons-primary-text-color: var(--color-primary);
+}
+```
+
+- **For:** the design system stays the single source of truth — when tokens
+  change, Ketch follows automatically, no edits.
+- **Against:** variable names are Ketch-internal and could change across SDK
+  versions; only covers what the theme models.
+
+**Use `html:root`, not `:root`.** Ketch injects its own `:root` block into
+`<head>` at runtime, so it comes after the project stylesheet and wins on equal
+specificity. `html:root` is one step higher and wins regardless of order.
+`:root { … !important }` also works; `html:root` is cleaner.
+
+#### Deriving the variable names
+
+The rule is mechanical: **take the theme value's dot path and replace dots with
+dashes, prefixed `--k-`.**
+
+```
+banner.container.background.color   →  --k-banner-container-background-color
+modal.purposeList.switchButtons.on.background.color
+                                    →  --k-modal-purposeList-switchButtons-on-background-color
+```
+
+Casing is preserved, so `purposeList` stays camelCase. Enumerate what's
+available for the property:
+
+```bash
+curl -s https://global.ketchcdn.com/web/v3/config/<org>/<property>/production/default/en/config.json \
+  | jq '.theme.banner, .theme.modal, .theme.preference'
+```
+
+Watch out for non-colour values. Radii are sometimes stored unitless (`"8"`),
+which is invalid in `border-radius: var(…)` — set those explicitly with a unit
+(`8px`) or handle them with direct CSS instead.
+
+### C. Direct CSS on the element IDs
+
+For anything the theme doesn't model — layout, stacking, spacing, responsive
+behaviour, fonts:
+
+```css
+#lanyard_root,
+#lanyard_root * {
+  font-family: var(--font-sans), system-ui, sans-serif !important;
+}
+
+@media (max-width: 640px) {
+  #ketch-banner {
+    inset-inline: 0 !important;
+    width: 100% !important;
+    border-radius: 0 !important;
+    padding-bottom: max(1rem, var(--safe-area-inset-bottom, 0px)) !important;
+  }
+
+  #ketch-banner-buttons-container-standard {
+    flex-direction: column !important;
+    width: 100% !important;
+  }
+}
+```
+
+`!important` is usually needed here because Ketch's internals are Tailwind
+classes with an `!` important prefix reading the variables (e.g.
+`!ketch-bg-[--k-banner-container-background-color]`).
+
+Ketch exposes safe-area values on its root for notched devices:
+`--safe-area-inset-top` / `-right` / `-bottom` / `-left`.
+
+- **For:** total control, reaches everything.
+- **Against:** couples to Ketch's DOM, so it's the first thing to break on an
+  SDK upgrade. Prefer B for colours and keep C for structure.
+
+### D. Replace the UI entirely
+
+Possible — suppress Ketch's experiences and drive consent with `setConsent` from
+a custom component. **Think hard before doing this.** You take on per-jurisdiction
+copy, GPC and ATT signal banners, vendor lists, TCF strings and the audit trail,
+which is the bulk of what the CMP is paid for. Only justified when design
+requirements genuinely cannot be met by A–C, and worth confirming with whoever
+owns compliance.
+
+## Verifying UI changes
+
+CSS against a third-party widget can't be verified from a build — check in a
+browser:
+
+1. Clear site data so the banner shows again (or use `ketch("showConsent")`).
+2. Banner: colours, fonts, button styles, and the link to the privacy policy.
+3. Open "customize settings": purpose toggles, accept/reject buttons, scrolling.
+4. Dismiss the banner and confirm the floating button is in the state you
+   intended — this is where a missing `!important` shows up.
+5. Mobile viewport, and a notched device if safe-area padding matters.
+6. Keyboard: tab through the banner and modal, confirm focus is visible and
+   trapped in the modal.
+
+## Testing a different jurisdiction
+
+The banner and preferences center render completely differently per
+jurisdiction, so "the toggles are locked" or "Accept All does nothing" is
+usually **not a bug** — it's the visitor resolving to a jurisdiction where every
+purpose is `disclosure` (notice-only). Ketch then shows each purpose as
+**"Always Active"** with the toggle disabled, and the accept/reject buttons have
+nothing to change. Check the legal basis before debugging the UI:
+
+```bash
+curl -s https://global.ketchcdn.com/web/v3/config/<org>/<property>/production/default/en/config.json \
+  | jq -r '.purposes[] | "\(.code) \(.legalBasisCode)"'
+```
+
+Force a jurisdiction instead of relying on geo-IP by setting an attribute on the
+root element:
+
+```html
+<html jurisdiction="gdpr">
+```
+
+For a quick manual check with no code change, Ketch also accepts a URL query
+parameter that sets the same thing:
+
+```
+https://example.com/?ketch_jurisdiction=gdpr
+```
+
+Verified against a real property: LatAm traffic normally resolves to
+`default` (notice-only), where consent is granted automatically and the
+banner won't re-show on reload — see the gotcha below.
+`?ketch_jurisdiction=gdpr` (or `US_Texas`, `US_California`, …) forces the
+banner to render for that jurisdiction instead, with real Accept/Reject
+buttons — no VPN needed. Use this to actually see the opt-in UI from a
+region that defaults to notice-only.
+
+In Next.js, drive it from a gitignored env var so it never ships:
+
+```tsx
+<html
+  lang="en"
+  {...(forcedJurisdiction
+    ? ({ jurisdiction: forcedJurisdiction } as Record<string, string>)
+    : {})}
+>
+```
+
+Ketch's resolution order, highest priority first:
+
+1. An override in Ketch's own storage
+2. `config.jurisdiction.code`
+3. **`document.documentElement.getAttribute("jurisdiction")`**
+4. A `dataLayer` variable, if the property configures one
+5. The region → jurisdiction map (`jurisdiction.scopes` in `boot.js`)
+6. `defaultJurisdictionCode`
+
+Because the attribute is checked before the region map, it works from anywhere
+with no VPN. Try `gdpr` or `US_California` for opt-in UI with live toggles,
+`US_Texas` for opt-out, `default` for notice-only.
+
+Countries absent from `jurisdiction.scopes` fall through to `default`. If the
+site has real traffic from a country that isn't mapped, that's a dashboard
+decision for whoever owns compliance — surface it rather than working around it.
+
+## Gotchas
+
+- **Opt-out and notice-only jurisdictions don't offer Reject, and the banner
+  won't re-show.** Once Ketch auto-grants a jurisdiction's default record,
+  that resolves `isResolved` the same way an explicit accept would — no
+  reload brings the banner back, and there's no Reject All to click if you
+  were expecting one. This is the jurisdiction's legal basis, not a bug in
+  the integration or a broken build. Force a different jurisdiction (above)
+  before assuming something's wrong.
+- **`options.appDivs`.** The property config can list element IDs that Ketch
+  gates on consent (commonly a chat widget container). If a third-party widget
+  mysteriously doesn't appear, check whether it's listed there.
+- **Ketch normalises margins/padding** inside `#lanyard_root` with its own
+  injected stylesheet. Reset-style rules of your own may be redundant or fight
+  it.
+- **Ketch's stylesheet is added on first experience render**, not at boot. A
+  rule that works on the banner may not have applied yet when you inspect
+  before it opens.
+- **Custom CSS in the dashboard.** The property supports a `customCss` field
+  injected at runtime. If overrides behave unpredictably, check whether
+  something is already set there before adding more CSS in the repo.