Repository Guidelines

Scope

Build a CDP-only network observability and debugging control plane for clark-browser/Chromium.
Collect and correlate CDP Network/Fetch HTTP(S), failure, cache, and WebSocket events.
Keep the MVP read-only. Any future request or response mutation must be explicit opt-in and default off.
Prefer the smallest correct change and reuse existing patterns before adding dependencies or abstractions.

Do not add VNC/noVNC, desktop streaming, or GUI browser control.
Do not add MITM, proxy certificates, CA injection, TLS interception, packet capture, or SSLKEYLOGFILE flows.
Do not add proxy pools, IP rotation, fingerprint generation, account operations, DOM scraping, or media decoding.

Never commit or log CDP tokens, cookies, Authorization, Set-Cookie, credentials, full sensitive bodies, or production data.
Use short-lived CDP credentials over a protected internal or TLS connection, with session isolation and auditable access.
Redact sensitive headers and bodies before persistence or export; enforce body, event, frame, and retention limits.
Treat response bodies as optional: cache, target closure, protocol behavior, or lifecycle timing may make them unavailable.
Report disconnects, target closure, dropped events, and body-read failures without stopping the browser workload.
Validate all external input and preserve compatibility of persisted schemas and exported data.

Keep commits focused; do not add speculative scaffolding, dependencies, CI, or an unconfirmed application stack.
Use local fixtures only. Never use production credentials, send real external messages, deploy, publish, or perform destructive data operations.
Add the smallest relevant test for non-trivial behavior.
Cover request-to-response completion/failure correlation, WebSocket frames, redaction, truncation, session isolation, pagination, disconnect recovery, and unavailable response bodies where applicable.
Run relevant tests and formatting checks before pushing.