# 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.

## Non-goals

- 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.

## Security and reliability

- 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.

## Development and tests

- 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.