# Contributing to the INFJ Bot

Thank you for your interest in the DRIFT / INFJ Bot project. This is a personal companion AI with a Jungian cognitive architecture, so contributions should align with the project's philosophical and technical goals.

## Development Setup

```bash
# Clone
git clone <repo-url>
cd infj_bot

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install dev tools (optional but recommended)
pip install ruff mypy bandit detect-secrets pytest

# Copy environment template
cp .env.example .env
# Edit .env with your API keys
```

## Project Structure

```
infj_bot/
  config.py              # Central config, path resolution, API key validation
  brain.py               # Core LLM inference (Gemini + local fallback)
  memory.py              # ChromaDB semantic memory with secret scrubbing
  commands.py            # CLI command router (~40+ commands)
  web_app.py             # FastAPI web UI + Observatory SSE
  emailer.py             # SMTP + Gmail MCP email backend
  rate_limit.py          # Token bucket rate limiters
  maintenance.py         # Automated pruning and upkeep tasks
  hive_mind/             # DRIFT multi-agent consensus system
    orchestrator.py      # Hive conductor
    consensus_engine.py  # Epistemic triangulation
    shared_memory.py     # Attributed semantic memory
    protocol/dcp.py      # DCP v1 message protocol
  ... (cognitive modules)
```

## Code Standards

- **Python 3.12+** required
- **Line length:** 100 characters (enforced by ruff)
- **Imports:** `isort` style — stdlib first, third-party second, local third
- **Type hints:** encouraged for new functions; not required for legacy modules
- **Logging:** use `logging.getLogger("infj_bot.<module>")`, never `print()` in library code
- **Exceptions:** catch specific exceptions; avoid bare `except:`
- **Security:** scrub secrets before persistence; validate all paths

## Git Workflow

1. **Branch:** `git checkout -b feature/short-description`
2. **Commit:** clear, imperative messages (`Add rate limiter`, `Fix path traversal`)
3. **Test:** run `python -m pytest tests/` before pushing
4. **Lint:** run `ruff check .` and `ruff format .`
5. **Push:** `git push origin feature/short-description`
6. **PR:** open against `main` with a clear description

## Running Tests

```bash
# Hive Mind tests
cd hive_mind && ../venv/bin/python -m pytest tests/ -q

# Bot module smoke tests
python -c "import config, brain, memory, rate_limit, maintenance; print('OK')"
```

## Areas That Need Help

- **Test coverage:** Most cognitive modules have zero tests
- **Type hints:** Legacy modules lack annotations
- **Documentation:** Cognitive architecture docs for new contributors
- **Performance:** ChromaDB query optimization for large collections
- **Security:** Audit tool execution paths for injection vectors

## Communication

- Open an issue before major architectural changes
- Keep PRs focused — one concern per PR
- Respect the project's philosophical tone (Jungian depth, not corporate AI)