init

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to GramPilot
+
+:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
+
+The following is a set of guidelines for contributing to **GramPilot**. GramPilot has evolved significantly from its original roots into an AI-driven, autonomous Vision-Language-Action (VLA) agent. 
+
+Please follow these guidelines when submitting issues or pull requests.
+
+## Table Of Contents
+- [How Can I Contribute?](#how-can-i-contribute)
+  - [Reporting Bugs](#reporting-bugs)
+  - [Suggesting Enhancements](#suggesting-enhancements)
+  - [Pull Requests](#pull-requests)
+- [Development Paradigms](#development-paradigms)
+- [Styleguides](#styleguides)
+
+---
+
+## How Can I Contribute?
+
+### Reporting Bugs
+Before filing an issue, please ensure the bug relates to GramPilot's core framework (e.g. Qdrant cache issues, VLA compilation timeouts, Active Inference crashes). Because GramPilot synthesizes its own UI Locators using VLMs, **do not open bugs about outdated Instagram UI Locators**. The bot heals itself using the Dojo Engine automatically.
+
+When filing an issue, please provide:
+* The exact device or emulator and Instagram version.
+* The error trace from `logs/marisaundmarc.log` containing the emojis (e.g. ⛩️ Dojo Engine traces or ⚖️ Active Inference states).
+* Do not submit tickets without terminal output logs.
+
+### Suggesting Enhancements
+We welcome architectural enhancements to the **Cognitive Stack**. 
+If you want to contribute, focus on logic that makes the bot more human or resilient:
+* Adding new `sensors` (like the Honeypot Radome) to evade IG protections.
+* Expanding `DopamineEngine` parameters for better pacing.
+* Enhancing the VLM Prompts in `compiler_engine.py` for more robust heuristics.
+
+### Pull Requests
+1. All changes must be tested locally.
+2. If you add a new Cognitive Engine, it must be properly integrated into the `bot_flow.py` loop without relying on hardcoded delays `sleep(5)`. Use the thermodynamic delays derived from `ActiveInference`.
+3. Do not re-introduce `config.yml` dependencies for deterministic actions (e.g. `max_likes`). We rely strictly on biological simulation.
+
+---
+
+## Development Paradigms
+
+1. **NO HARDCODED XPATHS**: Do not PR changes that look like `device.xpath('//android.widget.Button...')`. Use the semantic intents via `_execute_transition`.
+2. **NO HARDCODED PIXELS**: Never use hardcoded pixel coordinates for scrolling or swiping (e.g. `scroll(1000)`). Screens vary drastically in pixel density. Always use human-scale dimensions (cm) via `device.cm_to_pixels(4.5)` to ensure deterministic physical interaction scaling.
+3. **ASYNCHRONOUS AUTO-LABELING**: Blocking network calls during UI automation cause timing errors. Ensure heavy computation (VLM generation) happens in background threads (e.g., `dojo_engine.py`).
+4. **FAIL GRACEFULLY**: Instead of wrapping UI lookups in `try/except` and crashing, utilize the Shadow Mode (`predict_state`) so the agent can naturally press "Back" if confused.
+
+---
+
+## Styleguides
+All Python code must be formatted with `Black`.
+Follow standard Git commit messages.