docs: connector authoring guidelines for desktop/mobile portability

[volod-vana]

Connectors are written against the page API, not against a browser. Desktop implements it with Playwright + Chromium; mobile implements it with a native WebView shim. A connector that only assumes the page contract runs on both - one that assumes Chromium on a laptop does not.

This adds CONNECTOR-GUIDELINES.md documenting the rules that keep that true, plus a link from the "Building a new connector" section.

Every rule is a failure actually hit while running real connectors on both runtimes, not a hypothetical:

1. Detect state from APIs, not page chrome. The most common break. A login check keyed on nav[aria-label="Chat history"] / [data-testid="profile-button"] never fires on a phone viewport, so the connector waits forever for a login that already happened. A session-endpoint check is layout independent - and more robust on desktop too.
2. Make the run resumable. Mobile can lose the runtime mid-run (OS kills the WebView, user backgrounds the app). There is no pause-and-continue; only what you checkpointed survives.
3. Fetch from inside the page, do not intercept the network. Reading response bodies off the app's own traffic is desktop-only in practice - iOS has no API for it, Android only partial. Fine as a fallback, not as the primary data path.
4. Keep page.evaluate payloads self-contained. No in-page eval/new Function: strict CSP rejects them, and mobile has no debugger-protocol escape hatch the way desktop does.
5. Never require credentials from the driver. requestInput is optional and absent on mobile by design - we do not want the app handling a user's third-party password. Always keep the showBrowser + promptUser fallback, and treat the showBrowser URL as a hint.
6. Declare desktop-only capabilities and fail cleanly. Binary download + unzip, cross-origin iframes, network response bodies. A clean failure routes to desktop handoff; a silent one looks like a broken app.
7. Report progress and bound the work. Runtime scales with the user's data - a small account finishes in under a minute, a large one can run far longer. The UI can only be honest about that if the connector emits counts.
8. Do not assume desktop layout or viewport.

Also includes a capability matrix (desktop vs iOS vs Android) and a pre-PR checklist.

Context: written after running unmodified connectors from this repo on a phone through a page-API shim. Most of the corpus ports as-is; the exceptions are exactly the capabilities in rule 6.