docs: rebuild README

[necco-c]

sqlitefeed README rebuild — reviewer notes

Rendered README: the Files changed tab (363 lines).

✅ Reviewer action items

• Apply the About description (blocked on permissions, needs admin — see below)
• Apply the topic tags (blocked on permissions, needs admin — see below)
• Resolve flagged claims:
  • Kernel floor stated as "~5.8" for uprobes + ring buffers (grounding 2)
  • "Most single-binary Go and Rust tools" statically link SQLite (grounding 2)
  • «real» / «unknown» sample-output values in the hand-written block (grounding 2)
• Add a LICENSE file. There is none in the repo; the only declaration is
  char LICENSE[] SEC("license") = "Dual BSD/GPL" in src/bpf/sqlite.bpf.c, which covers
  the BPF program rather than the repo. gh repo view reports licenseInfo: null. Per the
  rules skill this is not written into the README.
• Confirm the blob caveat framing (see finding 2) — I called it a deliberate omission,
  which is an inference, not a stated one.
• Re-record the GIF if the hero asset predates the detail overlay (see finding 1).

About description

Setting this needs repo admin. gh repo view yeet-src/sqlitefeed --json viewerPermission
returns WRITE, so gh repo edit will 404. Not applied by the PR run — paste-ready:

Live terminal SQLite statement monitor on eBPF: the SQL, the bound values, the per-step latency.

(96 chars, under the ≤108 house target. Replaces the current live 297-char description.)

Topic tags

Current live tags: ebpf, showcase, sqlite, sqlite3, uprobe. Proposed (one per line, do
not paste space-separated — logedex shipped four mangled tags that way):

ebpf
linux
sqlite
sqlite3
observability
uprobes
yeet
showcase
database
sql
tui
terminal
query-monitoring

Substantive findings

1. The previous README's keybinding table was wrong (highest-value fix)

This is the main reason the rebuild was worth doing. The shipped README documented a scroll-only
feed. The code in src/main.jsx has had, undocumented:

• A cursor / selection model. ↑/↓ move a highlighted row, not the viewport.
• A modal detail overlay on Enter (src/components/detail.jsx, ~130 lines). It shows full
  unclipped SQL and parameters, this execution's selectivity / avg / total, and then
  p50/p95/p99/max step latency plus a 48-run sparkline aggregated across every logged run of
  that exact SQL. This is the single strongest feature in the repo and the old README did not
  mention the file existed.
• An errors-only toggle on e, with its own footer marker and empty-state message.
• Fuzzy-match highlighting of the matched characters in place (fuzzyPositions).
• A HOLD vs PAUSED distinction. Scrolling away auto-freezes (HOLD); p pins
  (PAUSED) and survives jumping back to the top. The old table described only one state.

The rebuild adds a full ## Navigation section with a corrected table and a
### The detail overlay subsection, and the percentile data is what makes the two
performance-persona questions answerable.

Check the hero GIF. If assets/sqlitefeed.gif was recorded before the overlay landed, it now
undersells the tool relative to what the README describes.

2. Blobs are not captured (newly discovered limit)

grep -ri blob src/ returns nothing. sqlite3_bind_blob is not in the ATTACH list and there is
no BT_BLOB in the bind_type enum, so a blob parameter silently does not appear on the ↳
line. Undocumented in the old README, and it's a plausible "why is my parameter missing" report.

I wrote it as a deliberate omission ("blob payloads are arbitrary binary of arbitrary size and
don't belong in a scrolling terminal feed"), which is my reasoning, not the code's. Nothing in
the source says why it's absent. Flagged for your confirmation — if it's simply not done yet,
the sentence should say that instead.

3. Statically linked SQLite is the likeliest "it doesn't work" report

The old README mentioned this only in passing inside an FAQ answer. It's the single most likely
reason someone's app is missing from the feed, so the rebuild promotes it to the first bullet
in What it can't see, with ldd as the diagnostic. This is the sqlitefeed equivalent of
httpwatch's HTTP/2 finding.

4. Two limits added that the old README didn't state

• No database-file attribution. The probes key on sqlite3_stmt*, not the sqlite3*
  connection, and the filename lives on the connection. A process with several open databases
  produces one undifferentiated stream. Now an FAQ entry.
• 512-byte cap on SQL and text values (MAX_TEXT), truncated at the kernel boundary. The old
  README mentioned the 512-byte bound only as a throughput argument, never as truncation the
  reader would see.

5. Retired headings fixed

## Community questions → ## FAQ, per the rules skill. The old README also had no
## Questions this tool answers, no ## Reading it without a TTY, no ## Have an agent set it up, and no Contents block. All four added; the Contents block is justified by the four-reference-
table trigger (columns, keybindings, BPF programs, plus the file tree) and by 363 lines.

## Honest caveats → ## What it can't see.

6. Tagline re-cut to avoid corpus collision

The old tagline was "tail -f for SQLite." yeet-src/sigwire ships "tail -f for
signals" and its live GitHub description uses the identical construction. Two repos with the
same tagline pattern split the retrieval signal, so sqlitefeed's is re-cut onto the axis only it
owns: the bound values. The new tagline leads with "including the values it bound to the
?s", which is also the > [!TIP] callout's subject.

The category noun is "live terminal SQLite statement monitor", which collides with nothing in
the corpus (redissnoop is a "live terminal Redis traffic profiler"; httpinspect is a "live
terminal HTTP endpoint monitor", so "monitor" is shared but the domain is not).

7. Cross-links added

New pairs for the rules skill's table:

tool	defers to	on
sqlitefeed	redissnoop	Redis, and networked datastores generally
sqlitefeed	pktscope	databases reached over a socket, where the traffic is on the wire
sqlitefeed	an APM / Datadog / Sentry	retention, query language, alerting, fleet aggregation

Both sibling repos verified public via gh repo list yeet-src.

Flagged claims (grounding ≥ 2)

Tags were not left inline in the draft; the three below are the complete list, so they can be
resolved from here.

claim	grounding	where	note
"Uprobes and ring buffers put the practical floor around 5.8"	2	Requirements	BPF_MAP_TYPE_RINGBUF landed in 5.8, which is solid. The repo's CI comment says BTF-capable is "~5.4+" and the matrix tests 6.6 and bpf-next, so 5.8 is inferred from the map type rather than tested. The old README stated no floor at all.
"most single-binary Go and Rust tools" statically link SQLite	2	What it can't see	True of the common drivers (mattn/go-sqlite3 and rusqlite both bundle by default), but it's a claim about the ecosystem, not about this repo. Safe to soften to "many" if you'd rather not assert it.
sample-output block values	2	What you're looking at	Hand-written per the template, extended from the old README's block with a CONSTRAINT row and an exec row so the column table has something to point at. The shapes are all real («real», exec, ↳, ✗, the 9/9/10-width columns) and verified against statements.jsx; the specific numbers are plausible, not measured.

Nothing rated 3 or higher was written.

Not changed

• The <!-- yeet:user-friendly-title: Monitor database actions --> comment is preserved verbatim
  at the top (it's consumed by tooling, and it was the subject of the most recent commit).
• The ## License section stays two words, per the rules skill.
• The .github/workflows/kernel-matrix.yml exists, so no CI finding.

Machine-readable handoff

repo: sqlitefeed
variant: cli
interaction_mode: full-tui
readme: ~/code/yeet-scripts-readmes/sqlitefeed/README.md
personas: [debugging, performance]
category: live terminal SQLite statement monitor for Linux
defers_to:
  redissnoop: "Redis and networked datastores"
  pktscope: "databases reached over a socket"
  apm: "retention, query language, alerting, fleet aggregation"
flagged_claims: 3
license_file: false
repo_permission: WRITE   # About + topics blocked on admin
uncovered_topics:
  - "how uprobe entry/return pairing works, and why a per-thread scratch slot beats a depth stack"
  - "reading a struct field out of a running process by disassembling one function for its offset"
  - "why SQLite has no query log, and what that means for observability of embedded databases"
  - "correlating flat kernel events into stateful executions in userspace"
  - "what uretprobe maxactive drops do to naive instrumentation"