feat(connector): M4 — @understudy/connector + publish pipeline

[gcharang]

Summary

The understudy-side half of M4 (consumer integration + published contract): the reference breakwater connector package consumers import, publish-ready npm metadata for both packages, and the changesets + GitHub Actions release pipeline. The remaining M4 half (metamind / smart-compliance Mastra agent + flowsafe approvals driving understudy end-to-end) is cross-repo and not in scope here.

packages/connector — @understudy/connector 0.1.0

connector	id	class	protocol commands
observe	browser.observe	read — no approval	snapshot (a11y/dom/screenshot), get_tabs, wait
act	browser.act	write — grant-gated, idempotent, dry-runnable, 60/min	click, type, navigate, key, scroll, switch_tab
fillCredential	browser.fill_credential	vaulted write, 30/min	fill_secret (opaque secretRef; plaintext never enters the Worker/model/audit)

Plus callBrowserWrite / callBrowserDryRun workflow helpers mirroring metamind's shipped intake/connectors.ts. Verified against anchorage breakwater v0.3.x source and the shipped M3 service contract — deliberate deltas from the smart-compliance docs sketch (which predates M3): bearer caller auth, fill_secret from protocol v0.3.0, full protocol coverage, an optional breakwater policies pass-through (audit logger, tenantIsolation, test fetch seam), and Mastra's silent input-validation sentinel normalized to a throw. resolve_ref stays unreachable (internal service↔extension probe; consumers use the dryRun flag).

Load-bearing fix caught in review: egress declares URL.hostname, not .host — .host carries :port, which breakwater's egress allowlist rejects at construction, so every wrangler dev (localhost:8787) consumer loop would have thrown.

Publish + release

• MIT license (root + per-package), files-scoped tarballs (5 files each; workspace:^ verified to rewrite to ^0.3.0), npm READMEs, full publish metadata for @understudy/protocol 0.3.0 and @understudy/connector 0.1.0.
• ci.yml (typecheck/test/build) + release.yml — single-branch changesets flow adapted from anchorage: Version Packages PR when changesets are pending, publish with tags/GitHub releases/provenance when not. First push to master publishes 0.3.0/0.1.0 directly (versions pre-set; no changeset file on purpose).
• Blocked on repo setup before merge does anything on npm: create the npm understudy org (scope verified unclaimed 2026-07-16) and add an automation-token NPM_TOKEN repo secret. Without it the publish step fails loudly (ENEEDAUTH); nothing partial happens.
• pnpm-workspace.yaml: minimumReleaseAgeExclude for @proofoftech/breakwater (every published version is younger than the 7-day supply-chain quarantine).

Docs

Root README's stale pre-Topology-1 header ("backend brain") rewritten; technical plan repo layout / Consumer integration / M4 status updated to point at packages/connector as the canonical reference.

Test plan

• pnpm -r typecheck — 4/4 projects clean
• pnpm -r test — 131 passed (protocol 19 / extension 37 / connector 22 / backend 53)
• npm pack --dry-run both packages — 5-file tarballs incl. LICENSE; connector tarball's protocol dep rewrites to ^0.3.0
• Quality gate (parallel quality-reviewer / architect / QA lanes): all clean after fixes — .hostname egress fix + regression test, audit/policies seam + test, QA's recommended coverage (rate-limit denial, wrong-connector grant, release-on-throw retry, wait-failure, validation-sentinel) folded in
• Post-merge: npm org + NPM_TOKEN secret, then master push publishes both packages (release.yml)

🤖 Generated with Claude Code