feat(semrush): add provider-neutral research adapter

[iannuttall]

What changed

• Replaces the legacy raw Semrush router with provider-neutral adapters for:
  • keyword metrics
  • keyword research
  • domain overview
  • ranked keywords
  • ranking pages
  • search competitors
• Adds seo providers semrush connect|status|disconnect.
• Stores the permanent Semrush Version 3 key in the system keychain, with the existing private local file fallback.
• Migrates the old config key and the temporary development credential envelope without exposing either value.
• Bounds provider rows and response bytes before acquisition, checks the free API-unit balance before paid work, and records native unit evidence.
• Uses the shared credential-scoped cache so repeated work does not spend more units.
• Removes the dead semrush_call registration and keeps the public MCP surface at the three generic discovery tools.
• Adds the public Semrush setup guide and links it from the research-provider docs.

Why

The old Semrush path was a provider-shaped passthrough with uncertain usage and test coverage. It also left a dead report-specific MCP registration behind after MCP discovery had moved to the shared report registry.

This change makes Semrush an optional acquisition adapter behind the same owned report contracts used by the CLI, library, and MCP server.

Version support

This adapter deliberately supports only the permanent, automatically generated Version 3 API key. Version 4 support was removed after the active key failed live acceptance against the current early-access keyword endpoint with both documented authorization forms.

Semrush marks the Version 3 keyword endpoints as deprecated. That state remains visible in report warnings and in the documentation.

User impact

Humans can connect once with a masked prompt:

seo providers semrush connect
seo providers semrush status --check

Agents and CI can use SEO_SEMRUSH_API_KEY without saving the key. Research continues through seo reports run <report-id> with "provider":"semrush"; there is no new MCP tool or skill.

Verification

Live Semrush acceptance

• Permanent Version 3 key verified with the free balance endpoint.
• Six bounded paid requests passed across all six capabilities.
• Clean corpus ceiling: 180 API units.
• Estimated units: 180.
• Reported actual units: 180.
• Observed balance change: 180.
• Repeated keyword request: cache hit with no network request.
• Two corpus executions consumed 360 units total. The first completed the paid requests but exposed an oversized transient HTTP error page on the final free balance check. The transport now classifies and retries non-success HTTP responses before reading their bodies; the clean rerun passed.

Resource bounds

The 10,000-row Semrush harness completed with:

• 10 bounded simulated paid requests
• 10 free balance checks
• 637,300 bytes read
• 743,510 logical cache bytes written
• 75,164-byte final snapshot
• no measured RSS growth

Repository and package checks

• pnpm build
• pnpm typecheck
• pnpm test
• pnpm lint
• pnpm build:web
• pnpm --filter @seo/web typecheck
• pnpm --filter @seo/web test
• pnpm deploy:web:dry-run
• pnpm pack --dry-run
• pnpm test:package-install
• pnpm security:secrets
• CLI help sweep, including the Semrush command group