# Phase 1: Capture and Classification - Context

**Gathered:** 2026-03-25
**Status:** Ready for planning

<domain>
## Phase Boundary

Live packet capture from a network interface, protocol classification into named traffic classes, CLI scaffolding with interface selection and verbose output. No audio synthesis — this phase validates the capture-to-classify pipeline only.

</domain>

<decisions>
## Implementation Decisions

### Protocol mapping
- **D-01:** Deep port map with 10+ classes: ICMP, DNS (53), HTTPS (443), HTTP (80), SSH (22), SMTP (25), NTP (123), DHCP (67/68), other-TCP, other-UDP
- **D-02:** Classification rules stored in a config-driven Go map/struct (not hardcoded switch statements) — designed so rules could later be loaded from a config file
- **D-03:** All unrecognized traffic grouped as a single "unknown" class until Phase 3 adds auto-clustering

### Privilege model
- **D-04:** Support Linux and macOS (not Windows)
- **D-05:** On permission failure, detect the OS and show platform-specific guidance: `sudo setcap cap_net_raw+ep ...` on Linux, `sudo ...` on macOS
- **D-06:** Prefer static binary with no runtime libpcap dependency — use pure-Go pcap backend (go-pcap) where possible

### Claude's Discretion
- CLI output formatting during capture (stderr layout, colors, table width)
- Default time window duration for aggregation buckets
- Default network interface selection when `-i` is omitted
- Verbose output format and level of detail

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

No external specs — requirements fully captured in decisions above and in:
- `.planning/PROJECT.md` — Project context, constraints, key decisions
- `.planning/REQUIREMENTS.md` — CAPT-01 through CAPT-04, CLAS-01, CLAS-03, CLAS-04
- `.planning/research/STACK.md` — Go library recommendations (gopacket fork, go-pcap, cobra)
- `.planning/research/PITFALLS.md` — CAP_NET_RAW silently fails on nosuid mounts, packet buffer overflow, gopacket fork status
- `.planning/research/ARCHITECTURE.md` — Pipeline architecture, component boundaries

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- None — greenfield project, no existing code

### Established Patterns
- None yet — Phase 1 establishes the patterns

### Integration Points
- Phase 2 will consume classified traffic data (WindowSnapshot structs) from this phase's pipeline
- The classifier's output format directly shapes the synthesis engine's input contract

</code_context>

<specifics>
## Specific Ideas

- The tool should feel like tcpdump in its CLI conventions (`-i`, `--list-interfaces`, stderr for stats)
- Protocol classification should be granular enough that the eventual audio output has clear sonic variety — 10+ distinct classes
- Error messages for privilege issues should be immediately actionable, not just "permission denied"

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 01-capture-and-classification*
*Context gathered: 2026-03-25*