@c15t/react 3.0.0-alpha.0 → 3.0.0-alpha.10

package/docs/guides/troubleshooting.md

@@ -1,68 +1,206 @@
 ---
-title: Troubleshoot consent
-description: Diagnose missing banners, early vendor requests, lost choices and
-  hydration differences.
+title: Troubleshooting
+description: Fix a missing banner, analytics that load before consent, choices
+  lost on reload, CORS errors, hydration differences, failed manifest downloads,
+  mode errors and failed static builds in c15t v3.
 group: guides
 ---
 
-## Why is there no banner?
-
-Inspect `resolution` and `promptRequirement` before changing styles. Pending or
-failed initialization, no matching rule, a valid stored choice and a rule that
-requires no prompt can all produce no banner for different reasons. A missing
-stylesheet can also make rendered controls appear incorrectly.
-
-Check the backend URL and Network response, then confirm the active policy for
-the visitor's location. Do not solve missing UI by granting every category or
-setting `enabled: false`: disabling the runtime permits optional loading.
-
-## Why does the UI disappear with a content blocker?
+## Start with three checks
 
-Check the browser Network panel for `ERR_BLOCKED_BY_CLIENT` or a failed dynamic
-import. Older c15t builds used component filenames such as
-`consent-dialog-*.js`, which some cookie-annoyance lists block. Update the c15t
-packages and rebuild the app. Current component modules use neutral filenames;
-public component imports stay the same. This also covers Vite development
-requests used by TanStack Start and other Vite integrations.
+Most problems show up in one of these places. Run them before changing code.
 
-Extensions can separately hide elements with cosmetic filters or block a
-configured backend URL. Check the failed request or hidden element to distinguish
-those cases from a missing component module.
+1. **Which c15t is running.** In the browser console, run `window.c15t`. v3
+   prints `{ version, pkg, mode, hosting }`, for example `mode: 'manifest'`
+   from `@c15t/nextjs`. `hosting` is `'inth'` or `'self-hosted'` once the
+   backend has answered `/init`, and `null` before then or without a backend. `undefined` means no c15t provider has mounted on this
+   page. A `window.c15tStore` object means the page runs v2. With the script
+   tag, `window.c15t` is the full browser API instead.
+2. **The backend request.** In DevTools Network, filter by your backend URL.
+   Look for `/init` or `/manifest` and check its status. A CORS error means
+   the backend does not trust your site's origin.
+3. **Consent state.** Add the c15t DevTools panel from your framework's guide.
+   It shows the resolved policy, whether a prompt is needed, each category's
+   permission and the scripts c15t manages.
 
-## Why does analytics run before a choice?
+Your framework's troubleshooting page covers adapter-specific failures, such
+as Next.js prerendering errors or SvelteKit hydration.
 
-Check effective permission under the selected policy, then find every loader
-for that vendor. Remove unconditional script tags, framework analytics plugins
-and duplicate tag-manager entries. c15t's script registration only controls the
-scripts registered with it.
+## "Can't resolve 'c15t/next'" or a missing export
 
-Google helpers intentionally load with Consent Mode defaults. A Google request
-is not by itself proof that its storage consent was granted. If your requirement
-is no request at all, do not use an always-loaded helper unchanged.
+npm's `latest` tag still points to c15t v2, which has no framework entry
+points. A plain `npm install c15t` therefore installs v2, and imports such as
+`c15t/next`, `c15t/react` or `ConsentRoot` fail with "Package subpath is not
+defined by exports" or "Module not found".
 
-## Why does a choice disappear on reload?
+Install the v3 release and check the lockfile:
 
-Check whether persistence is disabled, browser storage is blocked, the origin
-changed, or the receipt expired or no longer matches the current policy.
-A development example with `persistence: false` deliberately resets on reload.
-Do not "repair" persistence by saving permissions automatically on mount.
+| Package manager | Command                  |
+| :-------------- | :----------------------- |
+| npm             | `npm install c15t@alpha` |
+| pnpm            | `pnpm add c15t@alpha`    |
+| yarn            | `yarn add c15t@alpha`    |
+| bun             | `bun add c15t@alpha`     |
 
-## Why does hydration differ from server HTML?
+Keep every c15t package, including `@c15t/integrations`, on the same release.
+Mixing v2 and v3 packages is not supported.
 
-Use the adapter's request helper and pass the returned configuration unchanged
-to its boundary. Check that server and browser use the same backend and policy
-inputs. A module-level mutable runtime on a server can share one visitor's state
-with another request; create request-owned state instead.
-
-## Why does static hosting fail when development works?
-
-A static host has no app server for init routes, proxies or server functions.
-Use absolute external consent URLs or an explicitly local policy. Test the
-production output with a static file server, not the framework dev server.
-
-## Why does customization do nothing?
+## Why is there no banner?
 
-Check the imported stylesheet, the correct token or slot, and which element
-carries the state attribute. `data-variant` on a banner root is not a matching
-attribute on its child card. Check cascade layers and the Tailwind version
-before adding specificity. See [customization](../customization/overview.md).
+No banner is sometimes correct. Find out which case you have:
+
+| What DevTools shows                                | Cause                                                                                                                                                                                                          | Fix                                                                                                                                                                                                                                                    |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| The backend request failed or has a CORS error     | Wrong backend URL, or your origin is not trusted                                                                                                                                                               | Copy the URL from your Inth project exactly, including any path. Add the site's origin, such as `https://www.example.com` or `http://localhost:3000`, to the project's trusted origins.                                                                |
+| Requests go to `your-project.inth.app` and fail    | The placeholder backend URL from the guides is still in your code                                                                                                                                              | Replace `https://your-project.inth.app` with the URL from your Inth project, including any path prefix.                                                                                                                                                |
+| No backend request at all                          | No provider mounted, the provider runs in offline mode, or the page resolved from a bundled manifest                                                                                                           | Check `window.c15t`. `mode: 'manifest'` with no request is expected for a policy that does not depend on location. Otherwise confirm your framework's backend URL variable is set, as [consent modes](../concepts/modes.md#set-the-backend-url) lists. |
+| The policy resolved and no prompt is needed        | The visitor's location maps to a policy without a prompt, such as a US state without a privacy law in the recommended rules                                                                                    | Expected. Test from a location that needs a prompt. Server helpers such as Next.js `resolveConsent` accept a `country` override for testing; remove it before you deploy.                                                                              |
+| The policy resolved and a choice is stored         | A returning visitor                                                                                                                                                                                            | Expected. Clear site data or use a private window.                                                                                                                                                                                                     |
+| The banner is in the DOM but invisible or unstyled | c15t's rules are missing: `styles: false` without an imported stylesheet, a Content Security Policy that blocks c15t's `<style>` elements, Tailwind CSS 3's preflight, or a SvelteKit app without `c15tHandle` | See [stylesheets and CSS layers](../customization/stylesheets.md) for how your framework loads c15t's rules.                                                                                                                                           |
+
+Do not "fix" a missing banner by granting every category or turning c15t off.
+While the policy is unresolved, every optional category stays denied. Turning
+the runtime off lets optional scripts load.
+
+## Why does analytics load before the visitor chooses?
+
+c15t only controls scripts you register with it. Find every other loader:
+
+* A `<script>` tag in your HTML, layout or `_document`.
+* A framework package or plugin, such as `@next/third-parties`,
+  `@nuxt/scripts`, `nuxt-gtag` or a Vercel or Netlify analytics toggle.
+* A tag in Google Tag Manager that fires on page view.
+* An embed, such as a YouTube iframe, rendered without `ConsentGate`.
+
+Remove the extra loader and register the vendor through
+[integrations](../integrations/overview.md). To replace a framework package,
+follow [migrate from `@next/third-parties`](https://v3.c15t.com/docs/frameworks/next/scripts#migrate-from-nextthird-parties),
+[migrate from `@nuxt/scripts`](https://v3.c15t.com/docs/frameworks/nuxt/scripts#migrate-from-nuxtscripts)
+or [migrate from `nuxt-gtag`](https://v3.c15t.com/docs/frameworks/nuxt/scripts#migrate-from-nuxt-gtag).
+Then reload with the Network panel open and cache disabled. The vendor's
+domain should be absent until you allow its category.
+
+Also check the policy. Under an opt-out policy, optional categories are allowed
+before a choice, so the request is expected.
+
+Google Tag and Google Tag Manager are an exception by design. By default
+their helpers load before a choice and send Google Consent Mode signals, so a
+request to Google before consent is expected. If you need no request at all
+before consent, set `loadMode: 'after-consent'`; see
+[Google Tag Manager](../integrations/google-tag-manager.md#choose-when-the-container-loads).
+
+## Why does the choice disappear on reload?
+
+| Check                                                                                         | Fix                                                                                                             |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| After saving, does DevTools Application show a `c15t` cookie and a `c15t` localStorage entry? | If not, look for `persistence: false` in your config. Examples use it on purpose; production apps should not.   |
+| Does the browser block storage, for example in a sandboxed iframe or a strict privacy mode?   | The choice works for the current page only. Nothing to fix in your app.                                         |
+| Did the domain, subdomain or protocol change between visits?                                  | Cookies and localStorage are per origin. Serve the site from one origin, or share the cookie across subdomains. |
+| Did the policy change since the visitor chose?                                                | A changed policy, a new required category or an expired choice prompts again. This is intended.                 |
+
+Never save a choice automatically on page load to make persistence "stick".
+That records consent the visitor did not give.
+
+## Why does the page reload after saving preferences?
+
+A visitor turned off a category or vendor they had allowed. Scripts that
+already ran cannot be unloaded, so c15t reloads the page to start clean with
+only permitted code. Set `reloadOnConsentRevoked: false` if you clean up
+revoked vendors yourself; [clear on revocation for your framework](../integrations/overview.md#vendor-switches-and-cookie-cleanup)
+covers the options.
+
+## Why does the server HTML differ from the browser?
+
+Pass the value your framework's server helper returns to the provider
+unchanged. Do not merge it with defaults or rebuild it from permissions. Make
+sure the server and browser use the same backend URL, because two backends can
+resolve different policies.
+
+Never keep consent state in a module-level variable on the server. One
+visitor's state can leak into another request. Create it per request, as the
+framework guides do.
+
+## Why does the build fail to download the manifest?
+
+`manifest()` resolves from a policy snapshot that the build downloads from
+`${backendURL}/manifest`. A production build stops when the download fails,
+and dev logs the same message as a warning. Every framework uses the same
+messages, prefixed with the integration's name, such as
+`@c15t/nextjs/build`, `@c15t/core/build` (for `c15t/build`),
+`@c15t/tanstack-start/build`, `@c15t/vue/vite`, `@c15t/svelte/vite`,
+`@c15t/vue` (Nuxt) or `@c15t/astro`:
+
+| Message                                                                                                                                           | Cause                                                                                                                           | Fix                                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `could not fetch the consent manifest from <url> during the build (fetch failed: ...)`, with `ENOTFOUND`, `ECONNREFUSED` or another network error | The build cannot reach the backend                                                                                              | Build where the backend is reachable, or deploy with `C15T_ON_BUILD_ERROR=runtime`                                                             |
+| `... (no response within 10 seconds)`                                                                                                             | The backend did not answer in time                                                                                              | Check the backend, or build where it is reachable                                                                                              |
+| `... (/manifest responded 404 Not Found)`, or another status                                                                                      | The URL is not your project's backend, such as the `https://your-project.inth.app` placeholder or a URL missing its path prefix | Copy the backend URL exactly as Inth shows it                                                                                                  |
+| `... (/manifest returned an invalid consent manifest.)`                                                                                           | The URL answered with something other than a consent manifest, such as an HTML page                                             | Point the backend URL at the backend itself, not your site or a dashboard page                                                                 |
+| `no backend URL is set, so the build cannot fetch the consent manifest. Pass backendURL or set ...`                                               | No `backendURL` option and no backend URL variable                                                                              | Set the variable your framework reads; see [consent modes](../concepts/modes.md#set-the-backend-url)                                           |
+| `skipped the consent manifest fetch because "/api/c15t" is not an absolute http(s) URL, so the server fetches the policy at runtime.`             | A relative backend URL. A notice, not an error.                                                                                 | Pass the absolute backend URL. With `onBuildError: 'fail'`, this stops the build with `build-time manifests require an absolute upstream URL.` |
+| `C15T_ON_BUILD_ERROR must be 'runtime' or 'fail', received "..."`                                                                                 | The variable has another value                                                                                                  | Set it to `runtime` or `fail`, or unset it                                                                                                     |
+| `onBuildError must be 'runtime' or 'fail', received "..."`                                                                                        | The option has another value                                                                                                    | Pass `'runtime'` or `'fail'`                                                                                                                   |
+
+Each failure message ends with what to do next. In a production build:
+``Set `C15T_ON_BUILD_ERROR=runtime` (or `onBuildError: 'runtime'`) to deploy with runtime fetching.``
+The Vite plugins add one more fix. The plugin can't see a mode set in app
+code, so an app that uses `manifest({ manifestURL })` or
+`manifest({ source: 'runtime' })` should pass `source: 'runtime'` to
+`consentManifest()`, and the build skips the download.
+A failed download never reuses an older snapshot. With
+`C15T_ON_BUILD_ERROR=runtime`, the build finishes without a snapshot, and the
+manifest is fetched at runtime. Dev warnings end with
+`The server fetches it at runtime instead. A production build stops on this error.`
+
+[Consent modes](../concepts/modes.md#what-happens-when-the-download-fails)
+describes the policy and when the build skips the download.
+
+### A single-page app warns that the policy depends on location
+
+`consentManifest()` from `c15t/build` logs this warning when it downloads a
+policy with location rules:
+
+```txt
+@c15t/core/build: the consent policy depends on the visitor's location, which the browser doesn't know. Unless you pass `inputs` or `geoURL` to `manifest()`, every first visit still calls the backend's /init, so the bundled policy adds bytes without saving a request. Consider `mode: hosted()` instead.
+```
+
+Pass the visitor's `{ country, region }` as `manifest({ inputs })` when your
+edge knows it, or a `geoURL` that answers with it. Otherwise switch the mode
+to `hosted()`, which asks `/init` without bundling the policy.
+
+## Why does the provider say a mode is required?
+
+The browser throws when a provider or `init()` gets no mode, or a mode name
+instead of a factory:
+
+| Message                                                                                                                                                                                                               | Fix                                                                                                                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ``@c15t/react ConsentProvider: `mode` is required. Use manifest() or hosted().``                                                                                                                                      | Pass `mode`, such as `manifest()` from the same package. The start of the message names the package and the API that got no mode, such as `@c15t/svelte ConsentProvider` or `@c15t/core createConsentRuntime()`. Production builds name the package only: ``@c15t/react: `mode` is required.`` |
+| ``@c15t/browser: `mode` must be a factory, such as manifest(), hosted() or offline() from @c15t/browser. Mode names like "hosted" work only in the script-tag builds.``                                               | Import the factory and call it: `init({ mode: hosted() })`.                                                                                                                                                                                                                                    |
+| ``c15t: hosted() needs `backendURL`. Pass it, or add consentManifest() from c15t/build to your Vite config and set VITE_C15T_BACKEND_URL (or VITE_INTH_PROJECT_URL).``                                                | The React `hosted()` found no backend URL. `@c15t/browser` throws the same message prefixed `@c15t/browser:`. A production build prints only the first sentence.                                                                                                                               |
+| ``c15t: `mode` is the hosted() transport itself, so its code ships in the client bundle. Pass the hosted() your framework package exports instead: it is plain data, and the root loads the code only when it runs.`` | A warning outside production. A server-rendered root got a transport from `c15t/react`. Import the mode from your framework package. Next.js has its own wording; see [Next.js troubleshooting](https://v3.c15t.com/docs/frameworks/next/troubleshooting).                                     |
+
+## Why does the static build fail when development works?
+
+A static host serves files only. Route handlers, server functions, rewrites
+and proxies that worked under the dev server do not exist after deployment.
+Point the browser at the absolute backend URL from Inth instead of a
+same-origin `/api/c15t` path, then test the built output with a static file
+server, not the dev server. [Choose your setup](../concepts/choose-your-setup.md)
+lists the static path for each framework.
+
+## Why does the UI disappear with an ad blocker?
+
+Check the Network panel for `ERR_BLOCKED_BY_CLIENT`. Some filter lists block
+the consent backend's domain or old c15t chunk names such as
+`consent-dialog-*.js`. Current releases use neutral chunk names; update and
+rebuild. If the backend domain is blocked, the banner cannot load policy and
+every optional category stays denied.
+
+## Why does my theme do nothing?
+
+Check that c15t's rules load, that you set a token or slot the
+component actually reads, and that the state attribute you target is on the
+element you style. A `data-variant` on the banner root is not on its card.
+Check the Tailwind version and CSS layer order before adding specificity. See
+[customization](../customization/overview.md).

package/docs/guides/verify-consent.md

@@ -1,62 +1,109 @@
 ---
-title: Verify consent before shipping
-description: Test requests, policy resolution, persistence, navigation and
-  preference changes in a production build.
+title: Verify consent
+description: Check in a production build that vendor requests wait for consent,
+  rejection survives a reload, preferences reopen and privacy signals apply.
 group: guides
 ---
 
-## Establish the policy under test
+## What you are checking
 
-Use a fresh browser profile and a known policy. For an opt-in choice policy,
-optional requests should be absent before a choice. Opt-out and notice policies
-have different defaults; inspect the resolved rule rather than expecting every
-region to show the same banner. Keep test geography overrides out of production.
+A banner on screen proves only that the banner renders. Before shipping,
+confirm four things in a production build:
 
-Inventory scripts in your HTML, application code, tag manager, plugins and
-embeds. A c15t provider cannot make an independently loaded vendor wait for a
-choice. Remove duplicate loaders before interpreting the result.
+1. Optional vendors make no requests before the visitor allows them.
+2. A rejection survives a reload and a new tab.
+3. The visitor can reopen preferences and change their mind.
+4. The policy is right for each location you serve.
+
+Run the checks against `next build && next start`, `vite preview`, or your
+framework's equivalent. Dev servers load code differently and hide problems.
+
+## Set up the browser
+
+1. Open a private window, so no earlier choice is stored.
+2. Open DevTools, select Network, and turn on **Disable cache** and
+   **Preserve log**.
+3. List the vendors you expect, such as `posthog.com`, `googletagmanager.com`,
+   `connect.facebook.net` or `youtube-nocookie.com`. You will filter by each.
+
+Before testing, list every place a vendor could load: `<script>` tags,
+framework analytics plugins, tag manager tags and embeds. c15t cannot hold
+back code it does not load. Remove duplicates first, or the results mean
+nothing.
 
 ## Run the visitor flow
 
-| Action                                     | Check                                                                                    |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| Load without a stored choice               | Correct policy and prompt; category-gated vendors stay blocked when permission is denied |
-| Reject optional categories                 | Prompt closes; denied vendors remain blocked                                             |
-| Reload                                     | Valid rejection persists; no new choice event is emitted by hydration                    |
-| Reopen preferences                         | Settings remain reachable after the banner closes                                        |
-| Save one category                          | Only that category gets a new confirmation time                                          |
-| Navigate without reloading                 | One runtime remains active; no duplicate vendor initialization                           |
-| Revoke a grant                             | Future gated work stops and configured cleanup runs                                      |
-| Load with an expired or incompatible grant | It does not silently restore optional permissions                                        |
-| Block the consent backend                  | Failed resolution is observable; absence of a banner does not grant permission           |
-| Block browser storage                      | Interaction still works where supported; verify whether the choice survives reload       |
-
-Inspect Network before the page starts loading, with cache disabled for the test.
-Filter by the vendor's script and collection domains. Hiding an iframe after it
-loads is too late to prevent the initial request.
-
-Google Consent Mode integrations intentionally load their scripts and send
-consent signals. Test their default and update commands separately from a
-zero-request gate. See [Google Tag Manager](../integrations/google-tag-manager.md)
-and [Google Tag](../integrations/google-tag.md).
-
-## Test the production hosting shape
-
-For static sites, serve the generated files. Confirm no request depends on an
-API route or rewrite that only exists in development. For SSR, inspect the
-initial HTML and check that hydration does not change a valid stored choice.
-Test a direct visit as well as client navigation.
-
-For a cross-origin backend, check allowed origins, protocol and reachable URLs.
-A public backend URL is not an API secret. Keep credentials out of client props
-and public environment variables.
+| Step                                         | What to check                                                                                                     |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Load the page                                | The banner appears under an opt-in policy. Filter Network by each vendor domain; opt-in vendors show no requests. |
+| Click Reject                                 | The banner closes. Vendor domains still show no requests.                                                         |
+| Reload                                       | No banner. Still no vendor requests. DevTools Application shows a `c15t` cookie.                                  |
+| Open a new tab on the same site              | Same result as the reload.                                                                                        |
+| Open preferences from your footer link       | The dialog opens with the categories you rejected turned off.                                                     |
+| Allow one category and save                  | Only vendors in that category start loading. The others stay silent.                                              |
+| Turn that category off again                 | The page reloads, and the vendor does not load after the reload.                                                  |
+| Navigate between pages without a full reload | Each vendor loads once, not once per navigation.                                                                  |
+
+By default, Google Tag and Google Tag Manager load before consent on purpose
+and send Consent Mode signals. For them, check that the consent state in the
+request parameters changes when the visitor chooses, not that requests are
+absent. With `loadMode: 'after-consent'`, they follow the table above. See
+[Google Tag Manager](../integrations/google-tag-manager.md).
+
+## Check each location
+
+Policies usually differ by region. Test at least:
+
+* A location that needs a choice, such as Germany or the United Kingdom.
+* A location without a prompt, such as a US state without a privacy law in
+  your rules.
+* A request with no location headers at all. c15t applies your policy's
+  fallback for unknown locations; make sure that fallback is what you want.
+
+Use a VPN, your host's geolocation preview, or the `country` option on your
+framework's server helper while testing. Remove test overrides before you
+deploy.
+
+## Check privacy signals
+
+Turn on Global Privacy Control in the browser. Brave and DuckDuckGo send it by
+default; in Firefox, enable it in Privacy settings. Reload and confirm the
+categories your policy restricts for GPC are denied, without the visitor
+having clicked anything. Turn GPC off and confirm the restriction ends.
+
+## Check failure behavior
+
+Make the request that initializes consent fail, then reload. Depending on your
+setup, that is the backend `/init`, a same-origin init route, a manifest fetch,
+or the `/init` a bundled manifest falls back to when a regional policy needs a
+location the browser does not know.
+
+* For a request the browser makes, block it in DevTools (right-click the
+  request, then **Block request URL**).
+* When the server resolves consent before the page loads, the browser never
+  sees that request. Make it fail on the server instead, for example by
+  pointing the backend URL at an unreachable address for one run.
+* With a custom transport, make its `init` fail.
+
+No banner appears, and vendors that wait for consent send no requests. Skip this
+check only if the page makes no initialization request at all, such as a
+build-time manifest with no regional fallback. A helper that always loads, such
+as `gtag` with its default `loadMode`, still loads; check that it reports denied
+consent. A missing banner must never mean "allowed". Then undo the change and
+confirm the page recovers.
 
 ## Check the interface
 
-Use a narrow viewport, long translated labels and keyboard-only navigation.
-Check that blocking dialogs trap focus, return it to the trigger when closed,
-and do not leave scrolling locked. Non-blocking notices should allow interaction
-with the page. Test contrast and focus indicators after applying a theme.
+* Tab through the banner and dialog with the keyboard only. Focus stays inside
+  a modal dialog and returns to the button that opened it when it closes.
+* Set the viewport to 375 pixels wide and switch to a language with long
+  labels, such as German.
+* After applying your theme, check text contrast and that focus rings are
+  visible.
+
+## Record the result
 
-Record the policy, framework, deployment and observed request behavior with the
-test result. "The banner appears" is only one assertion.
+Write down the framework, the rendering mode, the policy you tested, and the
+requests you saw before and after consent. "The banner appears" is not a test
+result. If something fails, [troubleshooting](./troubleshooting.md)
+starts with three checks that locate most problems.