Browser — the authenticated-browser capability

The browser is an authenticated transport to the user's real sessions. Read
data from each site's own internal API (ground truth) and use the DOM only for
visuals + the few write buttons. Proven: on a hardened SPA the DOM yields ~0
useful data while an in-page API fetch returns the full structured truth.

Where each concern lives (three homes, one boundary)

• Capability = code. The social capture/search recipes are implemented in
  @agstudio/browser-social (the SOCIAL_PLATFORMS adapters +
  createLinkedInVoyager). Drive the adapter; don't re-derive a recipe by hand.
• Operator "how/when" = corpus playbook. The durable judgement a runtime
  agent carries (recon SOP, persona = four signals, person-id scoring,
  when-to-escalate-stealth, rate-limit + write-gating discipline) is the
  social-recon corpus playbook overlay, injected into the operator's prompt
  (projects/guilde/packages/builtins/src/knowledge/social-recon.ts; read path
  in apps/api/src/mastra/guilde-playbook-processors.ts). A runtime operator
  cannot read these dev skills — the playbook is its home for that knowledge.
• Dev-SOP = these skills. What you (building/debugging the stack) need:
  transport mechanics, the chrome-devtools-mcp tool surface, proven-live
  gotchas, the per-platform internal-API reference (a superset of what the
  adapters implement — includes gated write ops). This is the dev-facing mirror.

Golden rules

1. API-first for data — find the site's internal API; the DOM is the slow,
   obfuscated, anti-scraping surface. News/content sites are the exception →
   readability/ld+json (content IS the HTML). See reference/recon.md.
2. Fail fast — ~8 s timeouts, not 60 s. After 5-6 s it's ~90 % a hard hang.
3. Direct URL nav > clicking navigating-links (clicks that navigate hang).
4. Tab/focus discipline — list_pages before acting; re-assert
   select_page({pageId, bringToFront:true}) per op under multi-agent
   contention.
5. Clear cookie/consent gates — CMP banners + login/paywall cookies first.
6. Gate every write — acts as the user; explicit per-action confirmation.
7. Capture cheaply — snapshot/evaluate for data; screenshot only for pixels.
8. Blocked? → stealth. On a hard anti-bot block ("Sorry, you have been
   blocked" / Cloudflare / DataDome / 403-429-503), this Chrome chain won't
   recover — switch to the camofox-stealth MCP on agentproto:
   mcp_imported_call alias="camofox-stealth" toolName="scrape" (HTTP-first,
   auto-escalates) or stealth_snapshot. Needs the camofox server on :9377
   (launchd com.agentik.camofox). See
   projects/browser/apps/stealth-mcp/README.md.

Reference (read what you need)

• reference/transport.md — chain, connection/health, Chrome lifecycle,
  tabs/focus, timeouts, the 29-tool surface + arg gotchas.
• reference/capture.md — screenshots (full / element by uid / CSS / CDP
  clip) + selective content (snapshot / evaluate querySelector / ld+json /
  readability).
• reference/cookies.md — cookie inspection, CMP consent, paywall/session
  injection, the login gate.
• reference/recon.md — the method to find + drive a site's internal API
  (the SOP-of-SOP); per-app auth tricks.
• reference/writes.md — gated write discipline + rate-limiting.

Site skills (instances built on this)

linkedin (proven, deepest) · x-twitter · youtube · instagram · tiktok
· leboncoin · news-media. Each carries its internal API, auth/cookies,
recipes, and capture method. Invoke the site skill for site work; it leans on
this skill for the mechanics.

Quickstart

health: api 3040 · tunnel 3600 (/internal/forward→401) · daemon 18790 (/health→200)
   (else: agentproto serve --connect ws://localhost:3600/connect)
list_pages → select your tab → navigate/snapshot/evaluate → (data) in-page API fetch

Helper library (one-call primitives)

projects/guilde/apps/api/scripts/lib/browser.ts → createBrowser():
tabs() · focus(host|id) · nav · snapshot · evaluate · extract(selector) · screenshotElement(uid) · fetchJson(url, csrfCookie) · apiReqs(re) · click/fill/press · newTab/closeTab.
LinkedIn layer: createLinkedInVoyager(createBrowser()) —
createLinkedInVoyager from @agstudio/browser-social drives this
createBrowser() port
(liFetch · feed · profileActivity · profile · reactors(activityUrn) · searchContent(query) · messageDraft).
searchContent = keyword post search: walks the RSC result cards (hashed DOM,
no client-side URNs) then resolves real activity permalinks per /in/ author via
Voyager activity; /company/ authors keep the profile URL. STEALTH-preferred
equivalent: social-scrape.mts content linkedin "<query>" (camofox, distinct
session + WhatsApp re-auth alert). See the linkedin skill. Ad-hoc CLI:
tsx scripts/browse.ts <tabs|focus|nav|snapshot|extract|fetch|shot|reqs>.
Prefer these over ad-hoc scripts. (Validated: tabs + extract live.)