[jamescottrill]

Why

A new site used to start empty. Nothing was scanned until someone found Trigger Scan, the install snippet had to be pieced together from the docs, there was no way to tell whether the banner was actually on the site, and nothing said what to do next or in what order.

As someone adding a site, I want to be taken from an empty site to a working banner, so that my site is compliant without having to know the steps beforehand or guess whether they worked.

What changes

First scan and scan progress

• A new site is scanned as soon as it is created. POST /sites/ takes "start_scan": false to skip it.
• If the scan can't be queued, the site is still created and the scan shows as failed, ready to start again.
• The Scans tab shows pages scanned out of the total found, and cookies found so far, while a scan runs. It stops polling when nothing is running.
• The API runs scans through the scanner's new POST /scan/stream, which reports progress after each page.
• A running scan is only treated as lost after 10 minutes with no progress, not 10 minutes after it started. SCANNER_TIMEOUT_SECONDS now limits each page rather than the whole scan, so large sites that used to fail partway through now finish.
• Scheduled scans use the site's page limit and are skipped while a scan is already running. A retried scan keeps its page limit.

Install guide

• Each site's Overview shows Install on your site: the snippet for that site, a copy button, and instructions for any site, WordPress and Shopify.
• The snippet comes from CDN_BASE_URL and the new PUBLIC_API_URL, falling back to the admin UI's own address, which is right for the default deployments.
• The Helm chart's cdn.baseUrl defaults to empty instead of https://cdn.example.com.

Installation verification

• The site is marked installed the first time a page on one of its domains loads the banner. Pages on other domains don't count, and only the page address is kept, never its query string.
• Check now loads the home page as a first-time visitor through the scanner's new POST /check-install and reports on each check, from the page loading to the banner appearing, with a fix for each failure.
• The Overview and the Sites list show Not detected, Installed or Problem found.

Setup checklist

• A new site's Overview shows six steps: scan, review cookies, set up the banner, preview and publish, install, and check it's working.
• Each step is worked out from the site itself, so steps can be done in any order and the checklist stays right after a reload or when someone else does a step.
• Once every step is done, Dismiss hides it for everyone. Sites published before the checklist existed don't show it.
• The Sites list shows Setup 2 of 6 while a site is being set up, in place of the publish and install badges.
• An organisation with no sites sees Add your first site, with the form ready to fill in.

Upgrade

• Upgrade the scanner and the API together. An API on this version can't run scans against an older scanner. POST /scan is unchanged for anything else that calls it.
• Migration 0014 adds site_installations. Migration 0015 adds two setup columns to sites and marks already published sites as set up. Both run on startup and need no manual steps.
• CDN_BASE_URL was previously unused. If it is set to an address that doesn't serve consent-loader.js, the install snippet will be wrong. Snippets already on sites keep working.
• Installation detection records which site the banner's configuration requests came from, using a short-lived key in Redis. Nothing is recorded while Redis is unavailable, and the banner is unaffected.

See the upgrade notes in docs/deployment-guide.md, and docs/scanning.md, docs/installing.md and docs/setting-up-a-site.md for the user guides and API.

Testing

• API: 1,321 pytest tests pass, covering the first scan, progress, stale-scan recovery, installation detection and checks, and every setup step.
• Scanner: 212 pytest tests pass, covering the streaming endpoint and each installation check.
• Admin UI: 289 Vitest tests pass, and tsc -b is clean.
• Helm: helm lint passes. CDN_BASE_URL is only rendered when cdn.baseUrl is set.
• Migrations: upgrade, downgrade and re-upgrade checked on a fresh database. The upgrade also ran against a staging database with existing sites.
• End-to-end: the stack suite in the separate end-to-end repository covers installation detection and checks, and follows the setup checklist to a working banner in Chromium. All 54 stack specs pass.