docs: clarify NIP-66 methodology, data sourcing, and known gaps

[alltheseas]

Summary

Addresses documentation gaps surfaced by developer feedback on the NIP-66 relay liveness filtering recommendation. Developers reading the existing docs couldn't answer basic questions about the approach — this PR closes those gaps.

Gaps closed

• Data sourcing — explains kind 30166 events vs HTTP API, strict vs liveness modes, and how production integrations (NDK, Applesauce) differ from the benchmark tool
• Provider independence — clarifies there is no nostr.watch dependency; kind 30166 is a replaceable event any monitor can publish
• Tor/.onion handling — documents two distinct concerns: .onion URLs (already preserved) and clearnet relays accessed through Tor (known gap — liveness data reflects clearnet path, not Tor exit-node reachability)
• Safety guardrails — documents all six graceful-degradation guardrails with code references
• Benchmark context — explicitly states these are protocol-level measurements, not client-specific results
• Reproduction methodology — adds NIP-66 A/B comparison section to Benchmark-recreation.md with run-nip66-comparison.sh instructions

Files changed

• IMPLEMENTATION-GUIDE.md — FAQ-style subsections under the existing NIP-66 section
• Benchmark-recreation.md — NIP-66 liveness comparison methodology subsection
• README.md — one-line benchmark context clarification

Test plan

• Verify all code references (file paths, line-level claims) match actual source
• Verify NIP-66 spec quotes match NIP-66
• Confirm links to NIP66-COMPARISON-REPORT.md and NIP66-FOLLOW-COUNT-ANALYSIS.md resolve correctly

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Documentation
  • Enhanced documentation on NIP-66 liveness filtering with benchmark mode details (strict and liveness modes)
  • Added comprehensive guidance on data sources, relay filtering methodology, and usage examples
  • Updated relay filtering description with protocol-level benchmark references

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e53bf8f5-14a2-4e68-9c85-7e8098200753

📥 Commits

Reviewing files that changed from the base of the PR and between e38b3f9 and 6dbdd50.

📒 Files selected for processing (3)

• Benchmark-recreation.md
• IMPLEMENTATION-GUIDE.md
• README.md

---

📝 Walkthrough

Walkthrough

This PR adds comprehensive documentation about NIP-66 liveness comparison and pre-filtering across three documentation files, detailing the --nip66-filter flag, two filtering modes (strict and liveness), data sources, usage examples, and implementation considerations. No functional code changes are included.

Changes

Cohort / File(s)	Summary
NIP-66 Liveness Documentation Benchmark-recreation.md, IMPLEMENTATION-GUIDE.md	Added detailed sections explaining NIP-66 pre-filtering modes (strict/liveness), data sources (30166 relay monitor events and HTTP API), Tor/onion considerations, safety guardrails, and usage examples with scripts and commands. Content includes benchmark methodology references and UI latency handling patterns.
Dead Relay Filtering Reference README.md	Updated "Dead relay filtering" description with protocol-level benchmark reference and methodology link.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Fix tables: sort by 3yr desc, rewrite Key Findings #6: Modifies NIP-66 relay liveness documentation with an alternative 3-state (Online/Offline/Dead) model instead of the 2-mode approach introduced here.
• Add retention profiling, fix report accuracy, reframe real ceiling #22: Implements the NIP-66 filtering logic and example scripts (examples/nip66-relay-filter.ts) that this documentation directly references and describes.
• docs: cleanup §8 numbering, methodology, and checklist #45: Centralizes methodology and NIP-66 definitions in documentation that this PR expands upon.

Poem

🐰 A rabbit hops through docs with care,
NIP-66 filters here and there,
Liveness modes both strict and free,
Now all the relay truth can see! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately summarizes the main change: clarifying NIP-66 methodology, data sourcing, and known gaps, which is precisely what the PR documentation changes accomplish.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/nip66-methodology

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}