From 422a1e1d2e383b7aea0e2ba823ee8ad47c523922 Mon Sep 17 00:00:00 2001
From: leetcrypt <leetcrypt@users.noreply.github.com>
Date: Mon, 16 Feb 2026 12:49:39 -0800
Subject: [PATCH] docs: add comprehensive CONTRIBUTING.md for GhostArmyIntel
 collaboration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created detailed contributor guide including:

**Join Process:**
- Step-by-step onboarding (accept invite → clone → setup → contribute)
- Current contributors: leetcrypt (admin), Ringmast4r (invited)
- GhostArmyIntel organization integration options

**Collaboration Workflows:**
- Option 1: Transfer repo to GhostArmyIntel organization (recommended)
- Option 2: Fork to organization (independent development)
- Option 3: Direct collaborator access (current setup)

**Development Guide:**
- Codebase structure walkthrough
- Git workflow (feature branches, PRs, commit conventions)
- Testing procedures (unit tests, benchmarks)
- Priority tasks from REAL_CAPTURE_ANALYSIS.md

**Quick Start Tasks:**
- Add missing protocols (Acurite 02077M, GE Doorbell, Holtek HT12X)
- Implement decoded .sub file support (Priority 1 - fixes 45% failures)
- Improve real signal robustness (packet segmentation, noise tolerance)

**GhostArmyIntel Integration:**
- Links to related projects (wardriving-converter, WiGLE-Vault, OUI-Master-Database)
- Organization transfer instructions
- Fork workflow for org-owned development

Designed to onboard Ringmast4r and GhostArmyIntel team members with complete
context on project status, architecture, and contribution paths.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CONTRIBUTING.md | 429 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 429 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..8b83845
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,429 @@
+# Contributing to GigLez - IoT RF Device Mapping Platform
+
+**Welcome!** We're building a Wigle-style platform for Sub-GHz RF device mapping. This guide will help you join the project and start contributing.
+
+---
+
+## 🏛️ Project Overview
+
+**GigLez** is an open-source crowdsourced platform for mapping IoT RF devices (300-928 MHz). Think "Wigle.net for garage doors, weather stations, and doorbells."
+
+**Key Features:**
+- 6-component RF signature matching engine
+- 299 protocol database (RTL_433 imported)
+- GPS validation & privacy features
+- Real-world benchmarking infrastructure
+- Support for Flipper Zero, RTL-SDR, HackRF captures
+
+**Current Status:**
+- ✅ Core identification engine complete
+- ✅ 56 unit tests passing
+- ⚠️ 33% synthetic accuracy, 0% real-world (documented gap analysis)
+- 📊 Benchmarking & calibration in progress
+
+---
+
+## 👥 Current Contributors
+
+### Core Team
+- **leetcrypt** - Repository owner, core developer (admin access)
+- **Ringmast4r** - Invited collaborator (write access) - *Pending acceptance*
+
+### Organizations
+- **GhostArmyIntel** - Organization for wardriving & RF intelligence projects
+  - Projects: wardriving-converter, WiGLE-Vault, OUI-Master-Database
+
+---
+
+## 🚀 How to Join the Project
+
+### Step 1: Accept Your Invitation
+
+If you've been invited as a collaborator:
+
+1. **Check your email** for invitation from GitHub
+2. **Or visit:** https://github.com/notifications
+3. **Accept the invitation** to join `leetcrypt/giglez`
+4. You'll receive **write access** (push, pull, create branches/PRs)
+
+**Pending Invitations:**
+- Ringmast4r (invited 2026-02-16)
+
+### Step 2: Clone the Repository
+
+```bash
+# Clone the repo
+git clone https://github.com/leetcrypt/giglez.git
+cd giglez
+
+# Verify you have access
+git remote -v
+```
+
+### Step 3: Set Up Your Environment
+
+#### Option A: Python Virtual Environment
+```bash
+# Create virtual environment
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install dependencies (if requirements.txt exists)
+pip install -r requirements.txt
+
+# Run tests to verify setup
+python -m pytest tests/ -v
+```
+
+#### Option B: Development with Existing Tools
+If you already have Python 3.10+ and pytest:
+```bash
+# Just run the tests
+cd /path/to/giglez
+python -m pytest tests/ -v
+```
+
+### Step 4: Understand the Codebase
+
+**Key Directories:**
+```
+giglez/
+├── src/
+│   ├── matcher/           # RF device identification engine
+│   │   ├── device_identifier.py      # Unified API (iteration 6/6)
+│   │   ├── pattern_decoder.py        # Multi-factor scoring
+│   │   ├── timing_analyzer.py        # Pulse timing extraction
+│   │   ├── preamble_detector.py      # Sync pattern detection
+│   │   ├── frequency_fingerprint.py  # ISM band classification
+│   │   ├── statistical_classifier.py # Bayesian scoring
+│   │   └── protocol_database.py      # 299 protocol signatures
+│   ├── parser/
+│   │   └── sub_parser.py             # Flipper .sub file parser
+│   └── gps/
+│       └── validator.py              # GPS validation & privacy
+├── tests/
+│   ├── unit/                         # 56 unit tests
+│   ├── benchmark/                    # Synthetic signal testing
+│   └── real_captures/                # Real Flipper Zero files
+├── scripts/
+│   ├── benchmark.py                  # Accuracy benchmarking
+│   └── benchmark_real.py             # Real-world testing
+└── docs/
+    ├── REAL_CAPTURE_ANALYSIS.md      # 0% accuracy gap analysis
+    └── WARDRIVER_ONBOARDING.md       # RF community survey
+```
+
+**Read First:**
+1. `CLAUDE.md` - Project status & architecture
+2. `docs/REAL_CAPTURE_ANALYSIS.md` - Critical findings on real-world performance
+3. `docs/WARDRIVER_ONBOARDING.md` - Data format requirements
+
+### Step 5: Make Your First Contribution
+
+#### Quick Start Tasks (Good First Issues)
+
+**1. Add Missing Protocols** (Priority 2 fix - 27% of failures)
+- Add Acurite 02077M to protocol database
+- Add GE Doorbell 19297
+- Add Byron DB421E
+- Add Holtek HT12X (fan/LED remotes)
+
+**2. Test Real Captures**
+- Download more real .sub files from UberGuidoZ/Flipper
+- Run `scripts/benchmark_real.py`
+- Document which protocols work/fail
+
+**3. Improve Documentation**
+- Add examples to CONTRIBUTING.md
+- Create protocol database contribution guide
+- Document how to add new signal types
+
+**4. Fix Decoded .sub File Support** (Priority 1 fix - 45% of failures)
+- Implement parser for decoded Flipper files
+- Extract Protocol, Bit, Key, TE fields
+- Match by protocol name + timing element
+
+---
+
+## 🔄 Git Workflow
+
+### Standard Development Workflow
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/your-feature-name
+
+# 2. Make changes and commit
+git add .
+git commit -m "feat: add Acurite 02077M protocol support"
+
+# 3. Push to GitHub
+git push origin feature/your-feature-name
+
+# 4. Create Pull Request on GitHub
+# Visit: https://github.com/leetcrypt/giglez/pulls
+# Click "New Pull Request"
+```
+
+### Commit Message Convention
+
+Follow conventional commits:
+```
+feat: add new protocol support for Holtek HT12X
+fix: correct timing ratio calculation for Oregon Scientific
+docs: update CONTRIBUTING.md with fork workflow
+test: add unit tests for decoded .sub file parsing
+refactor: optimize preamble detection algorithm
+```
+
+### Branch Naming
+
+- `feature/protocol-xyz` - New protocol additions
+- `fix/timing-accuracy` - Bug fixes
+- `docs/contributing-guide` - Documentation
+- `test/real-captures` - Test improvements
+
+---
+
+## 🏗️ For GhostArmyIntel Organization
+
+### Option 1: Transfer Repository to Organization (Recommended)
+
+**Requires:** GhostArmyIntel organization admin to accept transfer
+
+**Process:**
+1. Repository owner (leetcrypt) initiates transfer:
+   ```bash
+   gh api -X POST /repos/leetcrypt/giglez/transfer \
+     -f new_owner=GhostArmyIntel
+   ```
+
+2. GhostArmyIntel org admin accepts transfer at:
+   https://github.com/settings/repositories
+
+3. Repository becomes: `GhostArmyIntel/giglez`
+
+4. leetcrypt is re-added as collaborator
+
+**Pros:**
+- Organization owns the repo
+- Professional branding
+- Team can manage collaborators
+- Fits with wardriving-converter, WiGLE-Vault projects
+
+**Cons:**
+- Requires org admin permission
+- URL changes (redirect is automatic)
+
+### Option 2: Fork to Organization
+
+**Process:**
+1. GhostArmyIntel member visits: https://github.com/leetcrypt/giglez
+2. Click "Fork" button
+3. Select "GhostArmyIntel" as owner
+4. Fork created at: `GhostArmyIntel/giglez`
+
+**Workflow:**
+```bash
+# Clone the fork
+git clone https://github.com/GhostArmyIntel/giglez.git
+cd giglez
+
+# Add upstream remote (original repo)
+git remote add upstream https://github.com/leetcrypt/giglez.git
+
+# Sync with upstream
+git fetch upstream
+git merge upstream/main
+```
+
+**Pros:**
+- Independent development
+- Can create org-specific features
+- Proper fork relationship
+
+**Cons:**
+- Two separate repositories
+- Need to sync regularly
+
+### Option 3: Collaborator Access (Current Setup)
+
+**Process:**
+1. Ringmast4r accepts invitation to leetcrypt/giglez
+2. Works directly on shared repository
+3. Creates branches and PRs
+
+**Pros:**
+- Simple, immediate access
+- Single source of truth
+
+**Cons:**
+- Not under GhostArmyIntel organization
+
+---
+
+## 📊 Current Priority Tasks
+
+Based on `docs/REAL_CAPTURE_ANALYSIS.md`:
+
+### Priority 1: Decoded .sub File Support (Fixes 45% of failures)
+**Impact:** 5/11 real captures failed because they're decoded, not RAW
+
+**Task:**
+```python
+# Implement in src/parser/sub_parser.py
+def parse_decoded_sub_file(filepath):
+    """Parse decoded Flipper .sub files"""
+    # Extract: Protocol, Bit, Key, TE
+    # Match by protocol name + timing element
+    # Return SignalMetadata with is_decoded=True
+```
+
+### Priority 2: Add Missing Protocols (Fixes 27% of failures)
+**Needed:**
+- Acurite 02077M (weather station)
+- GE Doorbell 19297
+- Byron DB421E
+- Holtek HT12X (LED/fan remotes)
+- LiftMaster (generic 433 MHz)
+
+**Task:**
+Add to `src/matcher/protocol_database.py`:
+```python
+Protocol(
+    name="Acurite 02077M",
+    category="weather_sensor",
+    frequency=433920000,
+    short_pulse_us=1000,
+    long_pulse_us=2000,
+    # ... etc
+)
+```
+
+### Priority 3: Improve Real Signal Robustness (Fixes 27% of failures)
+**Issues:**
+- Multi-packet transmissions (131 pulses vs 40 bits)
+- Signal noise beyond 15% tolerance
+
+**Tasks:**
+- Implement packet segmentation
+- Increase jitter tolerance from 15% → 25%
+- Add repetition detection
+
+---
+
+## 🧪 Testing Your Changes
+
+### Run All Tests
+```bash
+# All unit tests
+pytest tests/ -v
+
+# Specific test file
+pytest tests/unit/test_timing_analyzer.py -v
+
+# With coverage
+pytest tests/ --cov=src --cov-report=html
+```
+
+### Run Benchmarks
+```bash
+# Synthetic signal benchmark
+python scripts/benchmark.py
+
+# Real-world captures benchmark
+python scripts/benchmark_real.py
+```
+
+### Expected Output
+```
+REAL-WORLD BENCHMARK SUMMARY
+═══════════════════════════════
+Total Tests: 11
+
+TOP-K ACCURACY:
+  Top-1: 0.0% (0/11)   # Target: improve this!
+  Top-3: 0.0% (0/11)
+```
+
+---
+
+## 📞 Communication & Coordination
+
+### GitHub Discussions
+Use GitHub Issues for:
+- Bug reports
+- Feature requests
+- Protocol addition proposals
+- Questions about implementation
+
+### Pull Request Reviews
+- Tag @leetcrypt for code review
+- Tag @Ringmast4r for wardriving expertise
+- Wait for approval before merging
+
+### Project Board (Coming Soon)
+Track work on GitHub Projects:
+- To Do: Priority tasks from REAL_CAPTURE_ANALYSIS.md
+- In Progress: Current work
+- Done: Completed features
+
+---
+
+## 🎯 Long-Term Vision
+
+### Phase 1 (Current): Core Identification Engine
+- ✅ Multi-factor scoring
+- ✅ Protocol database (299 protocols)
+- ⚠️ Real-world accuracy (in progress)
+
+### Phase 2: Web Platform
+- Upload interface (drag .sub files + GPS)
+- Interactive map (Leaflet.js)
+- Device database browser
+
+### Phase 3: Community Features
+- Manual device ID submission
+- Photo uploads
+- Voting/verification system
+- Leaderboards
+
+### Phase 4: Multi-Format Support
+- rtl_433 JSON import
+- URH .complex files
+- GPX track parsing
+- Batch upload API
+
+---
+
+## 📄 License
+
+MIT License - See LICENSE file
+
+---
+
+## 🤝 Code of Conduct
+
+- Be respectful and professional
+- Provide constructive feedback
+- Help newcomers learn
+- Document your changes
+- Test before pushing
+
+---
+
+## ❓ Questions?
+
+**GitHub Issues:** https://github.com/leetcrypt/giglez/issues
+**Repository:** https://github.com/leetcrypt/giglez
+
+**Related GhostArmyIntel Projects:**
+- wardriving-converter: https://github.com/GhostArmyIntel/wardriving-converter
+- WiGLE-Vault: https://github.com/GhostArmyIntel/WiGLE-Vault
+- OUI-Master-Database: https://github.com/GhostArmyIntel/OUI-Master-Database
+
+---
+
+*"A Ringmast4r project honoring the WWII Ghost Army — blending art, code, and strategy into modern open-source signalcraft."*
+
+**Last Updated:** 2026-02-16