Add professional project structure and documentation

New files:
- LICENSE (MIT) - Required legal file
- CHANGELOG.md - Version history following Keep a Changelog
- CONTRIBUTING.md - Contributor guidelines
- CODE_OF_CONDUCT.md - Community standards
- .github/ISSUE_TEMPLATE/ - Bug report and feature request forms
- .github/PULL_REQUEST_TEMPLATE.md - PR checklist
- src/stegasoo/py.typed - PEP 561 type hint marker
- examples/ - Usage examples (basic, file embedding, channel keys)

Updated:
- README.md - Added CI status badges

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

examples/README.md

@@ -0,0 +1,48 @@
+# Stegasoo Examples
+
+This directory contains example scripts demonstrating how to use Stegasoo.
+
+## Prerequisites
+
+Install Stegasoo first:
+
+```bash
+pip install stegasoo
+# Or for development:
+pip install -e ".[all]"
+```
+
+## Examples
+
+### basic_usage.py
+
+Basic encode/decode workflow with a text message.
+
+```bash
+python basic_usage.py
+```
+
+### embed_file.py
+
+Embed and extract files (documents, images, etc.) inside carrier images.
+
+```bash
+python embed_file.py
+```
+
+### channel_keys.py
+
+Use channel keys to create private communication channels for groups.
+
+```bash
+python channel_keys.py
+```
+
+## Test Images
+
+You'll need to provide your own images:
+
+- `my_secret_photo.png` - Your reference photo (keep this secret!)
+- `carrier.png` - The image that will carry your hidden message
+
+For testing, you can use any PNG or BMP image. JPEG carriers are supported with DCT mode.

examples/basic_usage.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""
+Basic Stegasoo Usage Example
+
+This example demonstrates how to encode and decode a secret message
+using the Stegasoo library.
+"""
+
+from pathlib import Path
+
+import stegasoo
+
+
+def main():
+    # Load your images
+    # The reference photo is your "key" - keep it secret!
+    reference_photo = Path("my_secret_photo.png").read_bytes()
+    carrier_image = Path("carrier.png").read_bytes()
+
+    # Your secret message
+    message = "This is my secret message!"
+
+    # Your credentials
+    passphrase = "correct horse battery staple"  # Use 4+ words
+    pin = "123456"  # 6-9 digits
+
+    # === ENCODE ===
+    print("Encoding message...")
+    result = stegasoo.encode(
+        message=message,
+        reference_photo=reference_photo,
+        carrier_image=carrier_image,
+        passphrase=passphrase,
+        pin=pin,
+    )
+
+    # Save the stego image
+    output_path = Path(f"secret_{result.suggested_filename}")
+    output_path.write_bytes(result.stego_image)
+    print(f"Saved to: {output_path}")
+    print(f"Capacity used: {result.capacity_used_percent:.1f}%")
+
+    # === DECODE ===
+    print("\nDecoding message...")
+    stego_image = output_path.read_bytes()
+
+    decoded = stegasoo.decode(
+        stego_image=stego_image,
+        reference_photo=reference_photo,
+        passphrase=passphrase,
+        pin=pin,
+    )
+
+    print(f"Decoded message: {decoded.message}")
+    print(f"Message type: {decoded.payload_type}")
+
+
+if __name__ == "__main__":
+    main()

examples/channel_keys.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Channel Keys Example
+
+Channel keys allow you to create private communication channels.
+Only people with the same channel key can decode messages.
+"""
+
+from pathlib import Path
+
+import stegasoo
+from stegasoo.channel import generate_channel_key, get_channel_fingerprint
+
+
+def main():
+    # Generate a channel key for your group
+    channel_key = generate_channel_key()
+    fingerprint = get_channel_fingerprint(channel_key)
+
+    print("=== Channel Key Generated ===")
+    print(f"Key: {channel_key}")
+    print(f"Fingerprint: {fingerprint}")
+    print("\nShare this key securely with your group members!")
+    print("-" * 40)
+
+    # Load images
+    reference_photo = Path("my_secret_photo.png").read_bytes()
+    carrier_image = Path("carrier.png").read_bytes()
+
+    # Encode with channel key
+    print("\nEncoding message with channel key...")
+    result = stegasoo.encode(
+        message="Secret group message!",
+        reference_photo=reference_photo,
+        carrier_image=carrier_image,
+        passphrase="correct horse battery staple",
+        pin="123456",
+        channel_key=channel_key,  # Add the channel key
+    )
+
+    stego_data = result.stego_image
+    print(f"Encoded successfully!")
+
+    # Decode with correct channel key
+    print("\nDecoding with correct channel key...")
+    decoded = stegasoo.decode(
+        stego_image=stego_data,
+        reference_photo=reference_photo,
+        passphrase="correct horse battery staple",
+        pin="123456",
+        channel_key=channel_key,  # Same channel key
+    )
+    print(f"Message: {decoded.message}")
+
+    # Try to decode with wrong channel key
+    print("\nTrying to decode with wrong channel key...")
+    wrong_key = generate_channel_key()
+    try:
+        stegasoo.decode(
+            stego_image=stego_data,
+            reference_photo=reference_photo,
+            passphrase="correct horse battery staple",
+            pin="123456",
+            channel_key=wrong_key,  # Different channel key
+        )
+        print("ERROR: Should have failed!")
+    except (stegasoo.DecryptionError, stegasoo.ExtractionError):
+        print("Correctly rejected - wrong channel key!")
+
+
+if __name__ == "__main__":
+    main()

examples/embed_file.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+File Embedding Example
+
+This example demonstrates how to embed a file (like a document or image)
+inside a carrier image using Stegasoo.
+"""
+
+from pathlib import Path
+
+import stegasoo
+from stegasoo.models import FilePayload
+
+
+def main():
+    # Load images
+    reference_photo = Path("my_secret_photo.png").read_bytes()
+    carrier_image = Path("carrier.png").read_bytes()
+
+    # Load the file to embed
+    secret_file = Path("secret_document.pdf")
+    file_data = secret_file.read_bytes()
+
+    # Create a FilePayload
+    payload = FilePayload(
+        filename=secret_file.name,
+        data=file_data,
+        mime_type="application/pdf",
+    )
+
+    # Credentials
+    passphrase = "correct horse battery staple"
+    pin = "123456"
+
+    # Check capacity first
+    capacity = stegasoo.calculate_capacity(carrier_image)
+    print(f"Carrier capacity: {capacity['capacity_bytes']:,} bytes")
+    print(f"File size: {len(file_data):,} bytes")
+
+    if len(file_data) > capacity["capacity_bytes"]:
+        print("Error: File too large for this carrier!")
+        return
+
+    # Encode the file
+    print("\nEmbedding file...")
+    result = stegasoo.encode(
+        file_payload=payload,
+        reference_photo=reference_photo,
+        carrier_image=carrier_image,
+        passphrase=passphrase,
+        pin=pin,
+    )
+
+    output_path = Path(f"contains_file_{result.suggested_filename}")
+    output_path.write_bytes(result.stego_image)
+    print(f"Saved to: {output_path}")
+
+    # Decode and extract the file
+    print("\nExtracting file...")
+    decoded = stegasoo.decode(
+        stego_image=output_path.read_bytes(),
+        reference_photo=reference_photo,
+        passphrase=passphrase,
+        pin=pin,
+    )
+
+    if decoded.payload_type == "file":
+        extracted_path = Path(f"extracted_{decoded.filename}")
+        extracted_path.write_bytes(decoded.file_data)
+        print(f"Extracted: {extracted_path}")
+        print(f"Original filename: {decoded.filename}")
+        print(f"MIME type: {decoded.mime_type}")
+    else:
+        print(f"Unexpected payload type: {decoded.payload_type}")
+
+
+if __name__ == "__main__":
+    main()