README: rebuild around running it; layer write-up to docs/internals.md

[necco-c]

Rebuilds the README in the shape of apiwatch's: what httpscope is and how to run it first, the engineering detail behind a link. Julian's layer-by-layer write-up moves to docs/internals.md word for word, so nothing in it is lost.

Reviewer action items

• Julian: OK with the layer write-up living in docs/internals.md, with a short "Under the hood" summary in the README pointing into it?
• Set the About description (needs admin; gh repo edit returns 404 on write access):

  eBPF API drift detector for Linux: the HTTP APIs a host serves and calls, their shapes, and when they change

• Apply the topic tags (also admin): ebpf linux observability yeet yeetkit http api api-drift graphql tcx uprobes tls ai-agents
• Add a LICENSE file. There is none; every bpf/*/*.bpf.c declares SEC("license") = "GPL". The README has no license section until there is one.

What changed

• Added: tagline, linked badges, the demo gif (assets/httpscope.gif), a one-sentence definition, a six-line Quick start, an agent setup prompt under the first tip, "What the quick start needs" (Node 24 from NodeSource, yeetkit as a sibling checkout, make bpf), the demo traffic script, real output from a test host, Requirements, What it can't see, FAQ, and a 169-word "Under the hood".
• Moved: the six layers, the walk VM, building, the per-layer self-tests, the run-by-hand log and the kernel matrix to docs/internals.md, unchanged apart from em-dashes and links.
• Merged: "Layer 4: query" and the agent routes into "Let your agent read it for you".
• Removed: the per-layer status column ("done, verified on this box"), the colour-themes paragraph, the routes table (the /api page documents them), and the stale line about yeetkit being a dependency by absolute path.

Findings while writing it

1. Node 22 hangs; Node 24 doesn't. On a refused connect, Node 22's built-in WebSocket fires error and never close; Node 24 fires both. yeetkit's hub (src/host/bridge.mjs) reconnects only on close, so on Node 22, if the first dial lands before the isolate is listening, every page and /api call times out forever while the capture runs fine. The README requires Node 24 via NodeSource. A one-line yeetkit fix is to reconnect on error too; its engines still says >=20. (Debian 13's own nodejs is 20.19, end of life since April 2026.)
2. The Makefile comment is wrong. It says yeetkit runs make bpf for you. yeetkit's hasBpf() only looks for top-level bpf/*.bpf.c, and httpscope has one directory per tap, so a fresh clone fails with Failed to open BPF object …/bin/wire.bpf.o until you run make bpf.
3. Container TLS: the old README said both that discovery goes through /proc/<pid>/root "so containers work" and that containers are "not yet". discover.js has const container = false, and on a Docker host every container binary failed to attach. The README now says not yet.
4. OWN_PORTS is fixed at 3000 to 3002. Run the app on other ports and it captures its own traffic. Documented in the FAQ.
5. The kernel floor is 6.6 (TCX), now in Requirements and the badge.
6. arm64 now exercised. The full app ran on arm64 with kernel 6.12 (Debian 13): 19 interfaces including Docker bridges and veths, libssl and Node attached, a Dockerised gateway decoded with a status.new drift event.
7. Drift events can repeat. A cold test saw response.type.changed for the same field reported three times in the same millisecond. The README no longer says each change is reported once.

Cold agent test

A fresh Debian 13 arm64 VM (no yeet, no Node, signed out of yeet) given only the "Have an agent set it up" prompt, with the clone pointed at this branch's README:

• 355 s, 14 turns. Installed yeet and Node 24 with the NodeSource lines, cloned both repos side by side, make bpf built all 8 objects, npm run dev in tmux, /api/status up in about 6 s, ran the demo for three minutes.
• Caught 8 of the demo's 9 scheduled changes as drift events. The N+1 burst appears only as the burstMax metric (65 calls a second), and the health check's ok: false only through its new degraded key. The README now says value changes aren't drift.
• Checked independently afterwards: Node v24.21.0, all 8 objects in bin/, port 3000 listening, 4,294 transactions, drift present.
• Fixed from the run: it installed clang, llvm and libbpf-dev unprompted, so the prompt now says make bpf brings its own compiler.