Rebuild the README, add a demo build target and the hero GIF

[necco-c]

What changed

Added

• ## Questions this tool answers (11), weighted to performance engineers with debugging secondary. Includes the two mandatory questions: "is this a replacement for Datadog Profiler / Pyroscope / Parca" (answered no) and "when should I use this instead of perf top / py-spy".
• make demo / make clean-demo, building demo/cafe and demo/patterns with the host compiler at -O0 -g -fno-omit-frame-pointer.
• demo/README.md: what each workload shows per view, and the GIF recording recipe (terminal size, tour order, why each view needs a beat to fill).
• The hero GIF at assets/hotspot.gif.
• Gitignore rules for compiled demo output, keeping the .c files and README tracked.
• Sections the template requires and the old README lacked: agent setup prompt, a 60-second sampling primer, sample-output block plus column table, Reading it without a TTY, Testing across kernels, What it can't see, FAQ, Contents block.

Reshaped

• Navigation is now three tables, one per view, since the flat / flame / stream views have different keymaps.
• How it works splits into the BPF side and the JS side, covering cgroup scoping plus the target_pid filter, the BigInt wire format for kernel PCs, and batched symbolizeMany.

Fixed

• The README said the sampler runs at 99 Hz; profile.js defaults to 499.
• The README described symbolizing "the leaf frame (ips[0])"; the code symbolizes the interrupted PC and splits on the sign bit.
• The same two stale facts in src/bpf/sample.bpf.c's header comment.
• make clean now removes .dSYM bundles that clang leaves beside the demo binaries.

The old README documented only the flat table. Undocumented before this: the flame view (f), the stream timeline (t), the hover tooltip, --repo/--rev/--strip GitHub linking, OSC 52 clipboard copy (o), per-row source lines, freeze (␣), zoom, and --freq.

Verification

Run on kernel 6.12.96 aarch64, yeet 0.21.0, not inferred:

check	result
make	exit 0, bin/probe.bpf.o + 41.9kb bundle
make demo	exit 0, both workloads build
make clean	leaves exactly the three tracked files in demo/
sudo make veristat	on_sample success, 80 insns, 6 states
sampler attach	sampling 499 Hz (cgroup), 2794 samples in ~6s
user symbolization	toil resolved with cafe.c:28
kernel symbolization	el0_svc, invoke_syscall, __arch_clear_user, vfs_read named and labeled kernel
flame folding	21 depths, 57 named vs 1 unnamed after convergence
TUI end to end	driven in a PTY at 120x36: list renders, ⏎ arms the sampler, f/t switch views, q exits clean

The debugSyms claim was verified by experiment rather than assumed. Before installing libc6-dbg, 27.3% of a dd profile was ?? (libc.so.6); after, the same rows resolve to __internal_syscall_cancel (cancellation.c:40) and __memcpy_generic (memcpy.S:166).

Reviewer action items

• Make the repo public. It is currently private, and the README's agent-setup prompt tells readers to git clone it. I do not have admin (viewerPermission: WRITE), so this needs an org owner.
• Apply the About description (needs admin):

  eBPF CPU profiler for Linux: click a process, watch a live profile of user and kernel frames build.

• Apply topic tags (needs admin): ebpf bpf linux profiler profiling performance flamegraph perf-events observability cpu tracing yeet
• Confirm the kernel version floors in ## Requirements. perf_event BPF 4.9 and bpf_get_stack 4.18 are upstream introduction versions, not stated anywhere in the repo and not tested below 6.1 (the CI matrix floor). Happy to drop the numbers and keep only the verified BTF requirement.
• The GIF profiles idle processes (bash, postgres, 2 to 21 samples), never the cafe demo workload. The flame frame with the tooltip is excellent; the flat-table moments look sparse. Worth a re-record against ./demo/cafe if you want the table to sell itself, but not blocking.

Notes

## Reading it without a TTY is a "you can't" section. There is no import.meta.main self-test on the probe module, no --json and no one-shot mode, so unlike every sibling in the corpus there is no headless path. The template permits this and argues it beats omitting the section, so it ships that way and names the seam a contributor would build on (attachProfile() already exposes hot / stacks / total / status as signals).

No LICENSE file was added, per instruction. ## License states GPL-2.0. on the grounding of the BPF SEC("license") declaration.