Simplify agent development guidance

src/dns/AGENTS.md

@@ -0,0 +1,12 @@
+# DNS development notes
+
+Applies to `src/dns/` and its submodules.
+
+- Custom DNS is scoped to each request URL and redirect target.
+- Resolve A and AAAA concurrently. Allow progress when either family succeeds while preserving successful records, resolver diagnostic order, IPv6 scope IDs, and Happy Eyeballs staggering.
+- UDP queries advertise EDNS(0), randomize IDs, and fall back to TCP on truncation using the remaining timeout budget.
+- DoH uses RFC 8484 POST first and its existing JSON fallback. Share the `DohClient` across concurrent address-family lookups and keep response bodies bounded.
+- TLS/QUIC resolver hostnames use system DNS for bootstrap and retain SNI and certificate verification.
+- ECH discovery can be required even when a remote-resolving proxy bypasses A/AAAA lookup; do not couple those decisions.
+- DNS inspection must report partial fallback failures as failures rather than silently presenting incomplete success.
+- Reuse `custom.rs`, `wire.rs`, and `doh.rs`; keep inspection orchestration and rendering under `inspect.rs` and its helpers.

src/grpc/AGENTS.md

@@ -0,0 +1,10 @@
+# gRPC development notes
+
+Applies to `src/grpc/` and its submodules. Protobuf conversion and schema work must also follow `../proto/AGENTS.md`.
+
+- Reuse the standard gRPC framing, header, status, and compression helpers.
+- Reflection and descriptor reads must be bounded by decoded bytes and message count.
+- Client and bidirectional streaming input must convert incremental JSON directly to framed protobuf; do not materialize the complete input.
+- Enforce `framing::MAX_MESSAGE_SIZE` on incremental and buffered paths.
+- Preserve complete-frame streaming and trailers for formatted `application/grpc+proto` responses.
+- Keep plaintext loopback h2c support restricted to the gRPC path.

src/http/AGENTS.md

@@ -0,0 +1,16 @@
+# HTTP development notes
+
+Applies to `src/http/` and its submodules.
+
+- Transport code owns DNS/TCP/TLS/QUIC setup. Reuse `src/net.rs` dialing, proxy, timeout, and address-racing helpers.
+- Automatic HTTP/3 discovery applies only to eligible direct HTTPS requests. It must not delay normal TCP/TLS and must share the already-started connect-timeout budget.
+- Keep HTTP/3 cache entries bounded, origin/resolver scoped, authority-based, and expiring. Never learn Alt-Svc from insecure responses.
+- Retry protocol NACKs only when safe and when the request body is replayable.
+- Body descriptors must preserve replay behavior: files and multipart sources reopen; stdin streams once and errors if replay becomes necessary.
+- `Content-Length` inference stays centralized in `src/http/mod.rs` and runs only when neither `Content-Length` nor `Transfer-Encoding` was supplied.
+- Digest authentication validates challenges before replay checks and cleans up abandoned 401 bodies with bounded work.
+- Keep request/DoH/WebSocket origin TLS settings separate from HTTPS proxy TLS settings.
+- Response responsibilities remain split between `response/stdout.rs`, `response/stream.rs`, `response/formatters.rs`, and `response/metadata.rs`.
+- SSE, NDJSON, and gRPC stdout streaming use the shared callback driver. Keep parsing format-specific and buffering bounded.
+- Do not emit binary-looking bodies to terminal stdout unless the user explicitly forces stdout output.
+- Put MIME selection policy in `src/format/content_type.rs`; update user documentation for visible format or MIME changes.

src/proto/AGENTS.md

@@ -0,0 +1,9 @@
+# Protobuf development notes
+
+Applies to `src/proto/` and its submodules. Transport-level gRPC work must also follow `../grpc/AGENTS.md`.
+
+- Reuse shared descriptor discovery, schema, conversion, and JSON-stream parsing helpers.
+- Reflection and descriptor processing must remain bounded by decoded bytes and message count.
+- Streaming JSON conversion must process values incrementally rather than materializing all input.
+- Enforce gRPC framing message-size limits before allocating or encoding a frame.
+- Preserve local-schema and reflection behavior across unary, client-streaming, and bidirectional paths.

src/update/AGENTS.md

@@ -0,0 +1,11 @@
+# Update development notes
+
+Applies to `src/update/` and its submodules. Installer behavior is also covered by `tests/install.rs` and `tests/update.rs`.
+
+- Metadata, artifact, checksum, and redirect URLs require HTTPS except for explicit internal test overrides.
+- Update networking must not inherit origin-specific TLS versions, client authentication, insecure mode, or Unix-socket settings. It may retain proxy, DNS, timeout, verbosity, and custom-CA settings.
+- Stream artifacts while hashing them; do not buffer complete downloads in memory.
+- Preserve archive path validation and the existing streaming tar / temporary zip behavior.
+- Use `fileutil::FileLock`, atomic replacement, and parent-directory synchronization where supported.
+- Background checks remain nonblocking.
+- Keep installer completion setup opt-in and never edit shell startup files automatically.

src/websocket/AGENTS.md

@@ -0,0 +1,12 @@
+# WebSocket development notes
+
+Applies to `src/websocket/` and its submodules.
+
+- WebSocket handshakes require HTTP/1.1. Keep explicit HTTP/2 and HTTP/3 rejection at validation boundaries.
+- Reuse HTTP networking semantics for DNS, proxies, TLS, and connect-timeout budgeting; SOCKS5H resolves remotely while SOCKS5 resolves locally.
+- Non-interactive mode connects before consuming piped stdin, sends and receives concurrently, closes only the send half at EOF, and continues receiving.
+- Preserve empty text lines and automatic binary handling for invalid UTF-8.
+- Keep incoming frames and messages bounded. Never write incoming binary data to terminal stdout.
+- Lock and flush text stdout per message; treat broken pipes as normal termination.
+- Keep origin TLS options on `wss://`; reject TLS options for `ws://`.
+- Preserve session cookie loading and persistence around successful handshakes.

tests/AGENTS.md

@@ -0,0 +1,10 @@
+# Integration test development notes
+
+Applies to `tests/` and `tests/support/`.
+
+- Integration tests execute the compiled `fetch` binary. Put reusable servers and fixtures in the appropriate `tests/support/` module.
+- Bind TCP and UDP test servers to `127.0.0.1:0`; do not reserve fixed ports.
+- Use `mpsc` request notifications and `recv_timeout` rather than polling server state.
+- `run_fetch` isolates the HTTP/3 cache by default; preserve that isolation in new helpers.
+- CI runs integration tests with two test threads. If a socket test fails transiently with connection refusal or reset, diagnose with `-- --test-threads=1` before weakening assertions.
+- Keep waits bounded and diagnostics useful. Do not add arbitrary sleeps when an event or channel can signal readiness.