1  # ENVOY Xray: Project Context & Strategic Map
 2  
 3  > **Status:** V4 Private P2P Mesh (Active Development)
 4  > **Primary Transport:** Radicle + IPFS (via `bittersweet` seed)
 5  
 6  ## 📋 Mission Objective
 7  Build a zero-trust, decentralized agentic middleware that treats communication as a rigorous data exchange. We are currently using the system to develop itself.
 8  
 9  ## 🏗️ Architectural Layout
10  - **Engine (`/src`):** The logic. `envoy_core.py` (Cryptography), `radicle_util.py` (P2P Transport), `ipfs_util.py` (Data).
11  - **Blueprint (`/docs`):** The theory. `HANDOFF.md` (Onboarding), `PROTOCOL_V4.md` (Identity Spec).
12  - **Side-Channels:**
13      - **Matrix:** `ENVOY-LAB` space for human discussion and execution reports.
14      - **IRC:** `ENVOY-NET` (Ergo IRC) for real-time presence, heartbeats, and coordination.
15  - **Cargo (`/exchange`):** The shared life.
16      - `knowledge/`: Shared technical context.
17      - `prompts/tasks/`: Swarm task management.
18      - `threads/`: Human-Agent-Agent interaction logs.
19  
20  ## 🛠️ Operational API for Agents
21  When you join this swarm, you must follow these P2P rituals:
22  
23  ### 1. The Retrieval Pass
24  ```bash
25  # Fetch latest gossip from the mesh
26  rad sync --fetch
27  git fetch --all
28  git merge rad/main # Or peer branch
29  ```
30  
31  ### 2. The Interaction Loop
32  To communicate with another agent or the human:
33  1.  **Artifact State:** If sending data > 16KB, pin to IPFS via `src.ipfs_util.IPFSUtil`.
34  2.  **Logic Identity:** Calculate your `EnvoyChecksum`.
35  3.  **Intent:** Sign an **A-JWT Triad** linking your logic, the current git commit, and the artifact.
36  4.  **The Drop:** Commit the `.ajwt` file to `queue/` and run `rad sync --announce`.
37  5.  **Coordination:** Publish status or reports to Matrix/IRC using structured `ENVOY_*` headers.
38  
39  ## 🎯 Current Roadmap
40  - [x] **Task 001:** Invitation Module (AgentMail)
41  - [ ] **Task 002:** State Machine Bridge - Integrate `src/v4_adapter.py` into `exchange_v3` to retire Nextcloud transport.
42  - [ ] **Task 003:** Multimedia Onramp - Design the simplified web interface for 'normies'.
43  
44  ## 🔑 Key Identities
45  - **Local:** `did:key:z6MkovCK7dKvnLqtdwS3XqLXV16pB2P9D8oK2GsJaiqmYKqs` (local-envoy)
46  - **Seed:** `did:key:z6MkpUw5mKYQ442bn7ZjAX144KTwEafiXgEaTJCHKTezsrjj` (bittersweet)
47  - **IRC Server:** `irc.bittersweet.fi` (Port 6697, TLS)
48  - **Matrix Space:** `ENVOY-LAB`