[vxfemboy]

Resolves #170.

Overview

This pull request delivers a comprehensive restructuring and modernization of the project landing page (README.md) and operational documentation curriculum (docs/), transforming technical reference documentation into an accessible, high-conversion, and battle-tested guide suite for operators and developers.

Summary of Changes

1. Executive Landing Page (README.md)

• Clear Value Proposition: Immediate "What is yip?", target audience, core problem solved, and explicit "When to Use / When NOT to Use" boundaries.
• Streamlined 5-Step Quickstart: Complete walkthrough from installation and key generation to 2-node tunnel bringup and ping verification.
• Copy-Paste Minimal Config: Zero-guesswork starter yip.conf configuration.
• Architectural Narrative: "Why yip Exists" narrative detailing the regulatory and technical context of decentralized, loss-resilient mesh overlays.
• Curriculum Matrix: Prominent navigation table indexing the new numbered documentation series.

2. Numbered Documentation Curriculum (docs/)

• 01-getting-started.md: Operational onboarding, prerequisite matrix (Linux kernel, capabilities, sysctl), point-to-point tunnels, L2/TAP vs L3/TUN modes, rendezvous traversal, CA-gated mesh joining, and obfuscation quickstart.
• 02-configuration.md: Exhaustive parameter reference covering every yipd config key, CLI flag, environment variable, and daemon option, paired with production scenario catalogs (direct tunnel, STUN/relay NAT traversal, anti-DPI TLS/REALITY mimicry, CA-gated decentralized mesh).
• 03-architecture.md: In-depth protocol and datapath architecture, trait boundaries (Device, Transport, Crypto, Wire, IoDriver), dual-path pipeline (epoll vs io_uring + busy-polling), systematic Reed–Solomon FEC over GF(256), sliding-window ARQ feedback loop, and wire-level framing.
• 04-security-and-threat-model.md: Comprehensive cryptographic specifications covering Noise-IK + Kyber-768/ML-KEM PQ hybrid exchange, AEAD session framing (ChaCha20-Poly1305), anti-replay bitmasks (64-entry to 8192-entry adaptive), TAI64N anti-replay timestamps, CA root trust anchors, anti-DPI threat boundaries, and formal threat matrix.
• 05-benchmarking-and-performance.md: Complete performance interpretation and evaluation guide, testbed topologies, netem synthetic loss injection reproduction, latency distribution analysis, comparison charts vs WireGuard/OpenVPN/n2n, and SVG generation pipelines.
• 06-troubleshooting.md: Operational diagnostic runbook featuring decision-tree flowcharts, handshake failure diagnosis, NAT punch debugging, MTU/MSS clamping calculation, FEC tuning under severe burst loss, and kernel driver tracing.

3. Backwards-Compatible Legacy Redirects

• Transformed legacy documentation paths (docs/user-guide.md, docs/configuration.md, docs/motivation.md, docs/testing-and-benchmarking.md) into clean compatibility redirect documents linking directly to their canonical numbered counterparts to ensure zero link breakage across external links and bookmarks.

Verification & Quality Gates

All automated quality gates and test suites were executed and verified locally:

• python3 crates/yip-bench/generate-graphs.py --check (All SVG assets valid and up-to-date)
• python3 crates/yip-bench/generate-wire-format.py --check (Wire format SVG valid and up-to-date)
• pytest crates/yip-bench/tests/ (16 passed)
• cargo fmt --check (Passed cleanly)
• cargo clippy --workspace --all-targets -- -D warnings (0 warnings, 0 errors)
• cargo shear (No unused dependencies detected)
• cargo test --workspace (All 400+ unit and integration tests passing)