Replace the setup flow with a one-click pairing handshake

[henry-mosh]

Connecting a site took three trips between two systems and two secrets hand-carried in opposite directions:

Step	Where
Create a ck_live_… org key	CiteCue
Paste it into WordPress, click Save & test connection	WordPress
Enable delivery for the project	CiteCue
Copy the cws_… ingest secret out	WordPress → CiteCue
Verify with curl -si -A GPTBot …	a terminal

…and the settings screen showed all ten fields throughout, including a project dropdown that is necessarily empty until after the first successful call.

It is now one button.

The handshake

WordPress: [Connect to CiteCue]
        │  browser redirect
        ▼
{app}/connect/wordpress?site=…&state=…&return=…&v=…
        │  admin confirms the project; CiteCue mints a per-site key
        ▼  redirect back with ?citecue_code=…&citecue_state=…
WordPress verifies the state, then server-to-server:
        POST {app}/api/delivery/v2/connect/claim
             { code, site_url, rest_url, ingest_secret, plugin_version, woocommerce }
          →  { apiKey, publicKey, domain, ingest }

Nothing is copied in either direction: the plugin gets its key and project, CiteCue gets the site's address and content-push secret.

What a reviewer should look hardest at

The code is bearer-grade — whoever presents it receives an API key — so the safety properties are the point, and they're where I'd want a second pair of eyes:

• The state token is stored server-side, bound to the administrator who started the handshake, single-use, and burnt even on a wrong guess. It is the CSRF defence on the return leg, which cannot carry a WordPress nonce because the redirect originates at CiteCue. Citecue_Admin::maybe_claim_connect() therefore has no check_admin_referer — deliberately, with a comment saying so.
• The ingest secret travels only in the claim body, never through a browser redirect, and that request sets redirection => 0 — a redirect would be a chance to replay it at another host.
• Ingest stays off unless the response says ingest: true. CiteCue's connect screen is the only place the customer is told content can be pushed into their site, so it is the only place that may grant it. A response that omits the field never enables it — silence is not consent.

Two fixes that fell out of the restructure

• The partial setup form would have switched delivery off on save. sanitize() reads an absent checkbox as "off" — correct for the form that owns the checkbox, destructive for one that doesn't. Partial forms now carry what they don't render as hidden inputs (preserve_toggles()). Verified by mutation: removing the call fails test_the_api_key_fallback_does_not_switch_delivery_off.
• Settings::update() cached what it passed in rather than what was stored. sanitize() can legitimately store something else — an empty api_key means "keep the stored one", not "erase it" — so it now drops the cache and lets the next read see the truth. This is also what makes disconnect() behave the same in the filtered and unfiltered paths.

The screen

Two shapes now. Before connecting: one sentence, one button, with the API-key route collapsed underneath for installs that can't bounce a browser through CiteCue. After: a status card (project, delivery state, llms.txt, last verification ✓/✗) and only the switches an operator adjusts — API key, project selector and API base folded into Connection details. The two competing save buttons are gone.

Verify installation replaces the curl command: a loopback GET on /llms.txt as GPTBot, checking for the marker header. It runs automatically right after connecting, so "did it work?" is answered before it's asked. A 200 without the header is the full-page-cache misconfiguration — now named on screen instead of hiding in a terminal.

The API base moves behind a CITECUE_API_BASE constant (or the new citecue_pinned_api_base filter) and renders read-only when pinned.

Merging this alone changes nothing for customers

The server side doesn't exist yet, so the Connect button 404s until it ships. The API-key path is untouched and remains the working route meanwhile. docs/connect-handshake.md is the contract citecue_app needs — the confirm page, the claim endpoint, storage, and the error codes the plugin already renders.

The one part of that spec I'd not let slide: return must be origin-checked against site, or it's an open redirect that hands an org API key to whoever crafted the link.

Testing

34 new tests. 251 pass in both runs (composer test:core and composer test:woocommerce), phpcs clean, php -l clean.

Covered: the state token is single-use, burnt on a wrong guess, and rejected for a different admin; the secret leaves only in the claim body; the claim doesn't follow redirects; ingest stays off unless granted; every claim error code; a failed claim leaves the site unconnected; both page shapes render (well-formedness checked with a real HTML parser).

🤖 Generated with Claude Code