docs: update architecture docs with three-component overview (#1340)

* docs: update architecture docs with three-component overview

- Rewrite CLAUDE.md/AGENTS.md project overview to accurately describe the
  three-container architecture (Squid, Agent, API Proxy sidecar)
- Add "Three Container Components" section with IPs, roles, and
  required-vs-optional status for each container
- Fix outdated iptables description: setup now runs in a separate
  awf-iptables-init init container, not inside the agent entrypoint
- Document that squid.conf is injected via AWF_SQUID_CONFIG_B64 env var
  (not a file bind mount) to support Docker-in-Docker
- Add API Proxy Sidecar as a documented third component
- Update traffic flow diagram to show full lifecycle including init
  container, optional API proxy path, and cleanup
- Make AGENTS.md a symlink to CLAUDE.md so all agents share the same docs
- Rewrite README "What it does" → "How it works" with concise three-container
  description for public-facing clarity

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: fix proxy description — Squid is a forward proxy, not transparent

HTTPS uses HTTPS_PROXY env var (explicit CONNECT method).
HTTP falls through to iptables DNAT since lowercase http_proxy is
intentionally not set (httpoxy mitigation on Ubuntu 22.04).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: clarify HTTPS proxy behavior — tools bypassing HTTPS_PROXY get TLS error

Squid is a forward proxy; HTTPS without HTTPS_PROXY hits Squid via
iptables DNAT but the TLS handshake fails (Squid expects CONNECT).
Traffic is still blocked, just with a connection error not a 403.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: fix overstated filesystem access — selective mounts not blanket host FS

The agent uses granular bind mounts (system binaries ro, workspace rw,
whitelisted HOME subdirs rw) not a blanket host filesystem mount.
Sensitive paths like /etc/shadow and non-whitelisted home dirs are excluded.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: fix precision issues flagged in review

- Expand selective bind mounts list to include all mounted paths:
  /sbin, /lib64, /sys, /dev, /tmp, .anthropic, .rustup, group,
  nsswitch.conf, ld.so.cache, alternatives
- Fix "transparent proxy, no HTTP_PROXY env needed" — HTTP_PROXY and
  HTTPS_PROXY are always set; iptables DNAT is defense-in-depth fallback
- Fix API proxy port notation "10000–10002" → "10000, 10001, 10002, 10004"
  (discrete ports, 10003 is never bound)
- Clarify port 10001 example is Anthropic-specific, not the generic sidecar address
- Fix README "iptables rules block" → "redirect" (DNAT redirects to Squid,
  not a flat block)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: remove last "transparent access to the host filesystem" in overview

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: trim README how-it-works to three concise lines

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Mossaka