# 🚀 Getting Started with Irene Cipher

## Welcome!

This guide will help you get started with Irene Cipher, whether you're a **user** looking to encrypt data or a **developer** looking to contribute.

---

## 👤 For Users

### Installation

**From PyPI (Recommended)**:
```bash
pip install irene-cipher
```

**Verify Installation**:
```bash
python -c "import irene_cipher; print('✓ Irene Cipher installed successfully')"
```

### Your First Encryption

Create a file `my_first_encryption.py`:

```python
import irene_cipher

# Encrypt some text
password = "my_secure_password_123!"
secret_message = "This is my secret message"

print("Original:", secret_message)

# Encrypt
ciphertext = irene_cipher.encrypt_text(secret_message, password)
print(f"Encrypted: {ciphertext.hex()[:60]}...")

# Decrypt
decrypted = irene_cipher.decrypt_text(ciphertext, password)
print("Decrypted:", decrypted)

print("\n✓ Success! Your first encryption works!")
```

Run it:
```bash
python my_first_encryption.py
```

### Encrypt Your First File

```python
import irene_cipher

# Encrypt a file
irene_cipher.encrypt_file(
    "important_document.pdf",
    "important_document.pdf.enc",
    "my_password"
)
print("✓ File encrypted!")

# Decrypt it back
irene_cipher.decrypt_file(
    "important_document.pdf.enc",
    "important_document_decrypted.pdf",
    "my_password"
)
print("✓ File decrypted!")
```

### Next Steps for Users

1. **Read the docs**: [README.md](README.md)
2. **Try examples**: `python examples.py`
3. **Quick start**: `python quickstart.py`
4. **Best practices**: [BEST_PRACTICES.md](BEST_PRACTICES.md)
5. **FAQ**: [FAQ.md](FAQ.md)

---

## 👨‍💻 For Developers

### Prerequisites

1. **Rust** (1.70+):
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   ```

2. **Python** (3.8+):
   ```bash
   python --version  # Should be 3.8+
   ```

3. **Maturin**:
   ```bash
   pip install maturin
   ```

### Clone and Build

```bash
# Clone repository
git clone https://github.com/yourusername/irene-cipher.git
cd irene-cipher

# Build in development mode
maturin develop

# Or build with optimizations
maturin develop --release
```

### Run Tests

```bash
# Rust tests
cargo test

# Python tests
python test_irene_cipher.py

# Run examples
python examples.py
python quickstart.py
```

### Code Quality Checks

```bash
# Format code
cargo fmt

# Lint code
cargo clippy

# Security audit
cargo install cargo-audit
cargo audit
```

### Project Structure

```
irene-cipher/
├── src/                    # Rust source code
│   ├── lib.rs             # Library entry point
│   ├── crypto.rs          # Core crypto operations
│   ├── error.rs           # Error handling
│   ├── file_ops.rs        # File encryption
│   └── python_bindings.rs # Python bindings
├── python/                 # Python package
│   └── irene_cipher/
│       ├── __init__.py    # Module init
│       ├── __init__.pyi   # Type stubs
│       └── py.typed       # PEP 561 marker
├── Cargo.toml             # Rust config
├── pyproject.toml         # Python config
├── examples.py            # Examples
├── test_irene_cipher.py   # Tests
└── README.md              # Documentation
```

### Making Changes

1. **Create a branch**:
   ```bash
   git checkout -b feature/my-feature
   ```

2. **Make changes** in `src/`

3. **Rebuild**:
   ```bash
   maturin develop --release
   ```

4. **Test**:
   ```bash
   cargo test
   python test_irene_cipher.py
   ```

5. **Format and lint**:
   ```bash
   cargo fmt
   cargo clippy
   ```

6. **Commit and push**:
   ```bash
   git add .
   git commit -m "Add my feature"
   git push origin feature/my-feature
   ```

7. **Open pull request** on GitHub

### Understanding the Code

**Start here**:
1. `src/lib.rs` - Entry point, module organization
2. `src/crypto.rs` - Core encryption logic
3. `src/python_bindings.rs` - Python API
4. `src/file_ops.rs` - File streaming

**Key concepts**:
- **XChaCha20-Poly1305**: AEAD cipher (see `encrypt_bytes`)
- **Argon2id**: Password hashing (see `derive_key_from_password`)
- **Streaming**: Chunked file processing (see `encrypt_file`)
- **PyO3**: Rust-Python bridge (see `python_bindings.rs`)

### Next Steps for Developers

1. **Read architecture**: [PROJECT.md](PROJECT.md)
2. **Build guide**: [BUILDING.md](BUILDING.md)
3. **Contribute**: [CONTRIBUTING.md](CONTRIBUTING.md)
4. **Security**: [SECURITY.md](SECURITY.md)

---

## 🎓 Learning Path

### Beginner (User)

1. ✅ Install library
2. ✅ Try quickstart.py
3. ✅ Read README.md (API section)
4. ✅ Encrypt/decrypt text
5. ✅ Encrypt/decrypt files
6. ✅ Read BEST_PRACTICES.md

### Intermediate (Power User)

1. ✅ Read FAQ.md
2. ✅ Try all examples.py scenarios
3. ✅ Understand error handling
4. ✅ Password management best practices
5. ✅ Performance optimization
6. ✅ Integrate into your project

### Advanced (Developer/Contributor)

1. ✅ Set up development environment
2. ✅ Understand Rust code
3. ✅ Understand crypto algorithms
4. ✅ Run and write tests
5. ✅ Make contributions
6. ✅ Security review process

---

## 📚 Documentation Map

**Quick Reference**:
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - API cheat sheet

**User Documentation**:
- [README.md](README.md) - Main documentation
- [FAQ.md](FAQ.md) - Frequently asked questions
- [BEST_PRACTICES.md](BEST_PRACTICES.md) - Usage best practices
- [examples.py](examples.py) - Code examples
- [quickstart.py](quickstart.py) - Quick start

**Developer Documentation**:
- [PROJECT.md](PROJECT.md) - Project overview
- [BUILDING.md](BUILDING.md) - Build and publish guide
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
- [SECURITY.md](SECURITY.md) - Security policy

**Reference**:
- [CHANGELOG.md](CHANGELOG.md) - Version history
- [LICENSE](LICENSE) - MIT License
- [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) - Implementation details

---

## 🆘 Getting Help

**Questions?**
- Check [FAQ.md](FAQ.md) first
- Read [README.md](README.md)
- Open a GitHub Issue
- Start a GitHub Discussion

**Found a bug?**
- Open a GitHub Issue with:
  - Clear description
  - Steps to reproduce
  - Expected vs actual behavior
  - System info (OS, Python version)

**Security issue?**
- **DO NOT** open public issue
- Email: security@example.com
- See [SECURITY.md](SECURITY.md)

---

## 🎯 Quick Commands

### User Commands
```bash
# Install
pip install irene-cipher

# Verify
python -c "import irene_cipher; print('OK')"

# Examples
python examples.py
python quickstart.py
```

### Developer Commands
```bash
# Build
maturin develop --release

# Test
cargo test && python test_irene_cipher.py

# Quality
cargo fmt && cargo clippy

# Audit
cargo audit
```

---

## ✅ Checklist

### For Users
- [ ] Installed library
- [ ] Tried quickstart.py
- [ ] Encrypted first text
- [ ] Encrypted first file
- [ ] Read README.md
- [ ] Understood security warnings

### For Developers
- [ ] Installed Rust + maturin
- [ ] Cloned repository
- [ ] Built successfully
- [ ] Ran all tests (passed)
- [ ] Read CONTRIBUTING.md
- [ ] Explored source code

---

## 🎉 Success!

You're now ready to use or contribute to Irene Cipher!

**Remember**:
- 🔒 Use strong passwords (16+ characters)
- 📝 Read documentation when unsure
- 🐛 Report bugs via GitHub Issues
- 🔐 Report security issues privately
- 🤝 Contributions are welcome!

**Happy encrypting! 🚀**
