================================================================================
RBIO-MESH-KIT: Role-Based Identity Ownership
Version 1.0
================================================================================

Welcome to the RBIO-Mesh-Kit. This package contains everything you need to 
build a privacy mesh that rotates digital identities automatically, breaking 
the correlation chains used by surveillance systems.

This kit is designed for:
- Raspberry Pi 5 (running Raspberry Pi OS Lite 64-bit)
- 4+ Android Phones (running GrapheneOS or /e/OS)
- Self-hosted environments (Gitea, GitLab, or local file transfer)

--------------------------------------------------------------------------------
TABLE OF CONTENTS
--------------------------------------------------------------------------------
1. Quick Start Overview
2. Prerequisites
3. Part A: Setting Up the Raspberry Pi (The Brain)
4. Part B: Configuring the Android Phones (The Nodes)
5. Part C: Self-Hosting on Gitea (Optional but Recommended)
6. Troubleshooting & Support

--------------------------------------------------------------------------------
1. QUICK START OVERVIEW
--------------------------------------------------------------------------------
The system works in three steps:
1. The Pi 5 runs a Docker container that acts as the "Provisioning Server."
2. The phones connect to the Pi via Wi-Fi and listen for "Swap Commands."
3. When a trigger occurs (time or motion), the Pi sends a command, and the 
   phones instantly wipe their old identity and load a new one.

No physical SIM swaps. No manual reconfiguration. Just pure, automated privacy.

--------------------------------------------------------------------------------
2. PREREQUISITES
--------------------------------------------------------------------------------
Hardware:
- Raspberry Pi 5 (4GB or 8GB RAM recommended)
- MicroSD Card (Class 10, A2) or USB SSD
- 4 Android Phones (Samsung A51/A52 for /e/OS, Pixel 6a/7 for GrapheneOS)
- Power bank or stable power source

Software:
- Raspberry Pi OS Lite (64-bit) installed on the Pi
- Docker and Docker Compose installed on the Pi
- Termux (for GrapheneOS) or MacroDroid (for /e/OS) installed on phones
- A Wi-Fi network (local only, no internet access required for the mesh)

--------------------------------------------------------------------------------
3. PART A: SETTING UP THE RASPBERRY PI (THE BRAIN)
--------------------------------------------------------------------------------

STEP 1: Install the Operating System
- Flash Raspberry Pi OS Lite (64-bit) onto your MicroSD card or SSD.
- Enable SSH and configure Wi-Fi/Ethernet during the first boot.
- Log in to your Pi via SSH.

STEP 2: Install Docker
Run the following commands in your terminal:

  curl -fsSL https://get.docker.com -o get-docker.sh
  sudo sh get-docker.sh
  sudo usermod -aG docker $USER
  newgrp docker

STEP 3: Deploy the RBIO Stack
- Create a directory for the project:
  mkdir ~/rbio-mesh && cd ~/rbio-mesh

- Copy the contents of this ZIP file into this directory.
  (If transferring via USB, mount the drive and copy the files here.)

- Edit the configuration files (optional):
  nano config/thresholds.json
  (Set your desired time limits and distance triggers here.)

- Start the system:
  docker compose up -d

- Check the status:
  docker compose ps

You should see three containers running: "rbio-server", "rbio-mqtt", and "rbio-db".

STEP 4: Verify the Server
- Open a browser on your phone (connected to the same Wi-Fi).
- Go to: http://[PI-IP-ADDRESS]:5000
- You should see a simple "RBIO Provisioning Server" welcome page.

--------------------------------------------------------------------------------
4. PART B: CONFIGURING THE ANDROID PHONES (THE NODES)
--------------------------------------------------------------------------------

OPTION A: For GrapheneOS Users (Using Termux)
1. Install Termux from F-Droid (do not use the Play Store version).
2. Open Termux and run the bootstrap script:
   sh /path/to/phones/graphene/termux-bootstrap.sh
   (Replace "/path/to/..." with the actual path where you copied the files.)
3. The script will install Python and the MQTT client.
4. Edit the "heartbeat.py" file to enter your Pi's IP address.
5. Run the heartbeat script:
   python3 heartbeat.py
6. The phone is now listening. It will automatically swap roles when triggered.

OPTION B: For /e/OS Users (Using MacroDroid or Termux)
1. If using Termux: Follow the same steps as GrapheneOS above.
2. If using MacroDroid:
   - Open MacroDroid.
   - Import the "Role-Swap-Trigger.macro" file (found in phones/eos/).
   - Grant necessary permissions (Accessibility, Storage, Wi-Fi).
   - The macro will listen for the MQTT message and execute the swap.

NOTE: Ensure all phones are connected to the same local Wi-Fi network as the Pi.
Do not enable mobile data if you want to eliminate cellular metadata.

--------------------------------------------------------------------------------
5. PART C: SELF-HOSTING ON GITEA (RECOMMENDED)
--------------------------------------------------------------------------------
To maintain full sovereignty, we recommend hosting this kit on your own Gitea 
instance rather than downloading it from a public server every time.

STEP 1: Install Gitea on your Pi (or a separate server)
- Follow the official Gitea installation guide: https://docs.gitea.com/installation
- Ensure Gitea is running on a local port (e.g., 3000).

STEP 2: Create a New Repository
- Log in to your Gitea instance.
- Click "New Repository".
- Name it "rbio-mesh-kit".
- Set visibility to "Private" (so only you can access it).

STEP 3: Upload the Files
- You can upload the files via the Gitea web interface:
  1. Click "Upload Files".
  2. Drag and drop the entire contents of this ZIP file.
  3. Commit the changes.

OR

- Clone the empty repository on your Pi and push the files:
  git clone http://[YOUR-GITEA-IP]:3000/your-user/rbio-mesh-kit.git
  cd rbio-mesh-kit
  # Copy files from the ZIP into this folder
  git add .
  git commit -m "Initial RBIO Mesh Kit Upload"
  git push origin main

STEP 4: Distribute to Phones
- On your phones, you can clone this repository directly if you have Git installed 
  (via Termux):
  git clone http://[YOUR-GITEA-IP]:3000/your-user/rbio-mesh-kit.git
  
- Or, simply copy the files from the Pi to the phones via USB or local Wi-Fi 
  transfer apps (like Send Anywhere or KDE Connect).

WHY SELF-HOST?
- No reliance on external servers.
- Full control over version updates.
- No tracking of your download activity.

--------------------------------------------------------------------------------
6. TROUBLESHOOTING & SUPPORT
--------------------------------------------------------------------------------

Problem: The phone cannot connect to the Pi.
Solution: Check that the Pi's IP address is correct in the phone's script. 
Ensure the firewall on the Pi allows port 1883 (MQTT) and 5000 (Flask).

Problem: The role swap is not happening.
Solution: Check the Docker logs:
  docker compose logs -f rbio-server
Look for "Trigger detected" messages. If none appear, check your 
config/thresholds.json settings.

Problem: The phone battery drains quickly.
Solution: Reduce the "heartbeat" frequency in the config file. 
The default is every 5 minutes; you can increase this to 15 or 30 minutes.

For further assistance, consult the detailed guides in the /docs folder:
- pi-setup-guide.txt
- phone-setup-guide.txt
- self-hosting-gitea.txt

================================================================================
END OF README
================================================================================