README.md

Agents Docs

Canonical documentation home for overlord-agents.

The protocol end goal for this repo is native capability coverage across the oracle families we target where it materially improves acceptance, reachability, or harvest yield: Kad for indexing and notes, plus ED2K for server search, peer search, sharing, upload, and download. Milestones remain staged, but wire-compatible behavior stays mandatory where interoperability or traffic shape depends on it.

Release Policy

Release naming and metadata bump rules are shared across the active p2p-overlord repos and are owned by p2p-overlord-be/docs/RELEASE_POLICY.md. In a combined workspace, use ../../p2p-overlord-be/docs/RELEASE_POLICY.md. The first planned RC is 0.1.1-rc.1; Rust crate metadata stays on dev versions until release mode starts.

Kad

• Kad Docs Landing Page
• Implementation Reference
• KV6_001 Kad2 IPv6 Design
• Protocol Reference
• Parity Notes
• Observations
• Wire Sequences
• Oracle Differences
• Kad Background Budget Tracker
• Stock eMule community-0.60 Comparison

ED2K

• ED2K runtime and wire work currently lives alongside the Kad docs in the same reference set while parity is still being built out.
• The current canonical ED2K target is full stock eMule v0.72a parity, including deprecated legacy compatibility behavior. The only standing protocol exception is defunct ED2K PeerCache support.
• Deterministic ED2K server scenarios should use the eMuleBB goed2k-server fork exposed by the eMuleBB workspace manifest as workspace.repos.ed2k_server.

ED2K-specific planning and status docs:

• ED2K 0.72a Full Parity Tracker
• ED2K Firewalled Parity Matrix
• ED2K Parity State Machine
• ED2K Firewalled Plaintext Parity
• ED2K Firewalled Obfuscated Parity

Shared protocol reference docs currently reused by the ED2K work:

• Kad Docs Landing Page
• Implementation Reference
• KV6_001 Kad2 IPv6 Design
• Protocol Reference
• Observations
• Wire Sequences
• Stock eMule community-0.60 Comparison

Native Download Acceptance

• For plaintext/native ED2K acceptance runs, keep the capture file external to the repo and feed the target hash, file name, and file size through the enrich/download path directly.
• Set OVERLORD_LOG_DIR for the run so agent-ed2k-tcp-dump-*.jsonl captures source candidates, per-peer attempts, packet flow, and final completion evidence for comparison against the external packet capture.
• Accept the run only when the transfer manifest ends completed=true, the verified size matches the requested file size, and the final ED2K hash matches the requested file hash.

Repo Guards

• In the eMuleBB workspace, shared workspace policy lives in ../emulebb-tooling/docs/WORKSPACE-POLICY.md. In the standalone p2p-overlord workspace, shared workspace quality and opportunistic-refactoring policy lives in ../../p2p-overlord-tooling/docs/WORKSPACE_POLICY.md. This section keeps the Rust-specific guard notes.
• From ../p2p-overlord-tooling, run python -m overlord_tooling guard-tracked-files --repo-root ../p2p-overlord-agents to validate tracked files for local path leaks and configured personal-name filename leaks.
• The required Rust gate promotes clippy::too_many_arguments, clippy::type_complexity, and clippy::cognitive_complexity using the thresholds in ../clippy.toml.
• Keep clippy::too_many_lines advisory until the existing large session and protocol functions are refactored. For local inventory, run cargo clippy --workspace --all-targets --all-features -- -W clippy::all -W clippy::too_many_lines -W clippy::cognitive_complexity -W clippy::too_many_arguments -W clippy::type_complexity.