tcptop/.planning/quick/260322-27k-add-project-readme/260322-27k-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
quick	260322-27k	execute	1		README.md	true	quick-readme	truths artifacts key_links README.md exists at repo root with project overview, features, installation, usage, and build sections Content is Linux-only, no macOS instructions Placeholder section for animated TUI screenshot with recording tool suggestions path provides min_lines README.md Project README 80

Create a comprehensive README.md at the repository root for the tcptop project.

Purpose: First point of contact for anyone discovering the project — explains what it is, how to install, how to use, and how to build from source. Output: README.md

<execution_context> @/Users/zrowitsch/local_src/tcptop/.claude/get-shit-done/workflows/execute-plan.md @/Users/zrowitsch/local_src/tcptop/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/quick/260322-27k-add-project-readme/260322-27k-CONTEXT.md @tcptop/src/main.rs (CLI struct with all flags) @tcptop/src/tui/event.rs (keybindings reference) @tcptop/Cargo.toml (version, metadata) @rust-toolchain.toml (nightly pin) @doc/PACKAGING.md (packaging reference, do not duplicate) Task 1: Create README.md README.md Create README.md at the repo root with these sections in order:

1. Title and tagline — # tcptop followed by a one-line description: "A real-time, top-like TUI for per-connection network statistics, powered by eBPF." No badges.

2. Screenshot placeholder — A section with a placeholder for an animated terminal recording. Include a comment or note like:

   <!-- TODO: Add animated terminal recording -->
   > Screenshot coming soon. To create one, consider:
   > - [VHS](https://github.com/charmbracelet/vhs) by Charmbracelet — scriptable terminal recordings to GIF
   > - [asciinema](https://asciinema.org/) — terminal session recorder (renders as asciicast or GIF via agg)
   > - [ttygif](https://github.com/icholy/ttygif) — converts ttyrec recordings to GIF
   

3. Features — Bulleted list of key features:

   • Real-time per-connection view (bytes, packets, latency, state)
   • eBPF-based kernel tracing (low overhead, no polling)
   • Sortable table with mnemonic keys and column navigation
   • Live text filtering (/ to search)
   • Process attribution (PID and process name)
   • TCP and UDP support with protocol filtering
   • CSV logging mode for offline analysis (--log)
   • Bootstraps pre-existing connections on startup
   • Graceful privilege handling (clear error when not root)

4. Requirements — Linux only. List:

   • Linux kernel 5.15+ (BTF support required for eBPF CO-RE)
   • Root privileges (sudo) — required for eBPF program loading

5. Installation — Two sub-sections:

   • From .deb/.rpm — point to Releases page and show sudo dpkg -i / sudo rpm -i commands. Link to doc/PACKAGING.md for building packages from source.
   • From source — see "Building from Source" section below.

6. Usage — Show sudo tcptop as the basic invocation. Then a table or list of CLI flags with descriptions (derive from the Cli struct in main.rs):

   • --port <PORT> — filter by port (source or destination)
   • --pid <PID> — filter by process ID
   • --process <NAME> — filter by process name (substring match)
   • -i, --interface <IFACE> — network interface to monitor
   • --tcp — show only TCP connections
   • --udp — show only UDP connections
   • --interval <SECS> — refresh interval in seconds (default: 1)
   • --log <FILE> — log to CSV file (headless mode, no TUI)

   Then a Keyboard shortcuts sub-section as a table: | Key | Action | | q / Ctrl-C | Quit | | j / Down | Scroll down | | k / Up | Scroll up | | / | Enter filter mode | | Esc | Clear filter | | Enter | Confirm filter / Sort by selected column | | Tab / Right | Next column | | Shift-Tab / Left | Previous column | | ? | Toggle help overlay | | c | Toggle extra columns | | r / R | Sort by rate in / rate out | | p / P | Sort by PID / protocol | | n | Sort by process name | | s | Sort by state | | t | Sort by RTT | | a / A | Sort by local / remote address |

   Include 2-3 usage examples:

   sudo tcptop --port 443 --tcp
   sudo tcptop --pid 1234 --interval 2
   sudo tcptop --log connections.csv
   

7. Building from Source — Prerequisites and build steps:

   • Rust nightly toolchain (pinned via rust-toolchain.toml to nightly-2026-03-20)
   • bpf-linker — cargo install bpf-linker
   • LLVM 21+ (for bpf-linker on some systems)
   • Build command: cargo build --release -p tcptop
   • Binary location: target/release/tcptop
   • Note that cargo xtask is NOT used — aya-build handles eBPF compilation via build.rs automatically.

8. License — MIT (per Cargo.toml)

Do NOT include: contributing guidelines, architecture section, macOS instructions, CI badges. test -f README.md && wc -l README.md | awk '{if ($1 >= 80) print "OK: " $1 " lines"; else print "FAIL: only " $1 " lines"}' README.md exists at repo root with all specified sections, Linux-only focus, animated screenshot placeholder with tool recommendations, and accurate CLI/keybinding documentation

- README.md exists at repo root - Contains all 8 sections specified above - No macOS content - CLI flags match the actual Cli struct in main.rs - Keybindings match the actual event.rs handler - Build instructions reference the correct nightly version from rust-toolchain.toml

<success_criteria> README.md committed with comprehensive project documentation covering overview, features, installation, usage (CLI + keyboard), build from source, and license. Screenshot placeholder with recording tool suggestions included. </success_criteria>

After completion, create `.planning/quick/260322-27k-add-project-readme/260322-27k-SUMMARY.md`