docs: Add Seahorse integration documentation (#56)

Author: RECTOR

src/content/docs/frameworks/seahorse.md

@@ -0,0 +1,306 @@
+---
+title: Seahorse Integration
+description: Generate Seahorse-compatible Python code for Solana programs from LUMOS schemas
+---
+
+LUMOS supports generating code for Seahorse, a framework that lets you write Solana programs in Python.
+
+## What is Seahorse?
+
+[Seahorse](https://seahorse-lang.org/) is a Python framework that compiles to Anchor-compatible Rust code, enabling Python developers to write Solana programs. LUMOS generates Seahorse-compatible Python classes from your schemas.
+
+## When to Use Seahorse Mode
+
+Use Seahorse generation when:
+
+- Writing Solana programs in Python using Seahorse
+- Want Python-native type annotations
+- Building with the Seahorse framework ecosystem
+- Need shared schemas between Python and TypeScript/Rust
+
+## Schema Syntax
+
+Seahorse schemas use the same LUMOS syntax as Anchor:
+
+```rust
+#[solana]
+#[account]
+struct PlayerAccount {
+    wallet: PublicKey,
+    level: u16,
+    experience: u64,
+    username: String,
+}
+
+#[solana]
+enum GameState {
+    Active,
+    Paused,
+    Ended,
+}
+```
+
+## Generated Code
+
+### Python Output
+
+```python
+# Auto-generated by LUMOS for Seahorse
+# DO NOT EDIT - Changes will be overwritten
+
+from seahorse.prelude import *
+
+@account
+class PlayerAccount:
+    wallet: Pubkey
+    level: u16
+    experience: u64
+    username: str
+
+
+class GameState(IntEnum):
+    Active = 0
+    Paused = 1
+    Ended = 2
+```
+
+### Key Features
+
+- Uses `from seahorse.prelude import *` for Seahorse types
+- `@account` decorator for account structs
+- Native Seahorse types (`u8`, `u16`, `u64`, `Pubkey`)
+- Python `IntEnum` for unit enums
+- No explicit Borsh schemas (Seahorse handles serialization)
+
+---
+
+## Usage
+
+### Generate Seahorse Code
+
+```bash
+# Generate Seahorse Python code
+lumos generate schema.lumos --lang seahorse
+
+# Generate multiple languages including Seahorse
+lumos generate schema.lumos --lang rust,typescript,seahorse
+
+# Dry-run to preview output
+lumos generate schema.lumos --lang seahorse --dry-run
+```
+
+### Output Structure
+
+```
+project/
+├── schema.lumos          # Source schema
+├── generated.py          # Generated Seahorse code
+└── programs/
+    └── my_program/
+        └── src/
+            └── lib.rs    # Use generated types
+```
+
+### Using in Seahorse Program
+
+```python
+# programs_py/my_program.py
+from seahorse.prelude import *
+from generated import PlayerAccount, GameState
+
+declare_id('...')
+
+@instruction
+def initialize_player(
+    owner: Signer,
+    player: Empty[PlayerAccount],
+):
+    player = player.init(
+        payer=owner,
+        seeds=['player', owner],
+    )
+    player.wallet = owner.key()
+    player.level = 1
+    player.experience = 0
+    player.username = ""
+```
+
+---
+
+## Type Mapping
+
+| LUMOS Type | Seahorse Type | Notes |
+|------------|---------------|-------|
+| `u8`, `u16`, `u32`, `u64` | `u8`, `u16`, `u32`, `u64` | Native Seahorse types |
+| `i8`, `i16`, `i32`, `i64` | `i8`, `i16`, `i32`, `i64` | Signed integers |
+| `u128`, `i128` | `u128`, `i128` | Large integers |
+| `bool` | `bool` | Python boolean |
+| `String` | `str` | Python string |
+| `PublicKey` | `Pubkey` | Seahorse Pubkey type |
+| `[T]` | `List[T]` | Dynamic arrays |
+| `[T; N]` | `Array[T, N]` | Fixed-size arrays |
+| `Option<T>` | `T \| None` | Optional fields |
+
+---
+
+## Comparison: Seahorse vs Standard Python
+
+| Feature | Seahorse | Standard Python |
+|---------|----------|-----------------|
+| Import | `seahorse.prelude` | `dataclasses`, `solders` |
+| Decorator | `@account` | `@dataclass` |
+| Types | `u16`, `u64`, `Pubkey` | `int`, `Pubkey` |
+| Serialization | Automatic | `borsh-construct` |
+| Use case | Solana programs | Client-side code |
+
+### When to Choose Seahorse
+
+- **Writing programs**: Building on-chain logic in Python
+- **Type safety**: Native Rust-like types in Python
+- **Seahorse ecosystem**: Using Seahorse's decorators and patterns
+
+### When to Choose Standard Python
+
+- **Client code**: Building Python backends for Solana dApps
+- **Data analysis**: Processing blockchain data
+- **Testing**: Writing test scripts for Solana programs
+
+---
+
+## Advanced Features
+
+### Complex Enums
+
+```rust
+#[solana]
+enum GameEvent {
+    Started,
+    PlayerJoined { player: PublicKey },
+    ScoreUpdate { player: PublicKey, score: u64 },
+}
+```
+
+Generates:
+
+```python
+from seahorse.prelude import *
+from dataclasses import dataclass
+
+# Variant types
+@dataclass
+class GameEventStarted:
+    pass
+
+@dataclass
+class GameEventPlayerJoined:
+    field0: Pubkey
+
+@dataclass
+class GameEventScoreUpdate:
+    player: Pubkey
+    score: u64
+
+GameEvent = GameEventStarted | GameEventPlayerJoined | GameEventScoreUpdate
+```
+
+### Optional Fields
+
+```rust
+#[solana]
+#[account]
+struct Profile {
+    wallet: PublicKey,
+    nickname: Option<String>,
+}
+```
+
+Generates:
+
+```python
+@account
+class Profile:
+    wallet: Pubkey
+    nickname: str | None
+```
+
+### Fixed Arrays
+
+```rust
+#[solana]
+#[account]
+struct Vault {
+    authorities: [PublicKey; 3],
+    balances: [u64; 10],
+}
+```
+
+Generates:
+
+```python
+@account
+class Vault:
+    authorities: Array[Pubkey, 3]
+    balances: Array[u64, 10]
+```
+
+---
+
+## Dependencies
+
+Add Seahorse to your project:
+
+```bash
+# Install Seahorse CLI
+cargo install seahorse-dev
+
+# Initialize Seahorse project
+seahorse init my-project
+```
+
+Your `pyproject.toml` or project structure should include Seahorse:
+
+```toml
+[tool.seahorse]
+program_name = "my_program"
+```
+
+---
+
+## Best Practices
+
+### 1. Keep Schemas in Sync
+
+Generate code whenever schemas change:
+
+```bash
+lumos generate schema.lumos --lang seahorse,typescript
+```
+
+### 2. Use Version Control
+
+Add generated files to `.gitignore` or commit them based on your workflow:
+
+```gitignore
+# Option 1: Ignore generated files
+generated.py
+
+# Option 2: Commit generated files for visibility
+# (No ignore needed)
+```
+
+### 3. Validate Before Compiling
+
+```bash
+lumos validate schema.lumos
+lumos generate schema.lumos --lang seahorse
+seahorse build
+```
+
+---
+
+## See Also
+
+- [Standard Python Generator](/api/generators#python) - For client-side Python code
+- [Anchor Integration](/frameworks/anchor) - For Anchor Rust programs
+- [Type System](/api/types) - Complete type reference
+- [CLI Reference](/cli/generate) - Full CLI documentation