docs: Add comprehensive architecture documentation

[solidsnakedev]

Overview

This PR adds extensive architecture and user documentation for the Evolution SDK.

Architecture Documentation

Core Architecture Concepts

• Devnet: Local Cardano network orchestration with Docker containers, deterministic genesis UTxO calculation using blake2b hashing, and container lifecycle management
• Transaction Flow: Complete build phase state machine with 7 phases showing how transactions progress from selection through finalization
• Coin Selection: Largest-first algorithm explanation with multi-asset selection patterns and custom algorithm support
• Script Evaluation: UPLC execution with pluggable evaluator interface, emphasizing custom evaluator support (Aiken, Plu-ts)
• Unfrack Optimization: UTxO consolidation strategy for minimizing transaction size and handling fragmentation

User Documentation Sections

• Introduction: Getting started guide, installation, migration from Lucid, platform compatibility
• Core Concepts: Addresses, transactions, assets, time handling, encoding formats
• Smart Contracts: Locking/spending scripts, datums, redeemers, reference scripts
• Advanced Features: Staking, governance (DReps, voting), querying, custom providers
• Development: Testing strategies, wallet management, client configuration

Documentation Philosophy

First Principles Approach

• No TypeScript code or type definitions in architecture docs
• Concepts explained through behavior and process flow
• Focus on "why" before "how"

Visual Communication

• One Mermaid diagram per concept
• Proper color contrast for accessibility (black text on light backgrounds, white on dark)
• Clear visual hierarchy with stroke widths and color coding

Content Organization

• Architecture docs focus on internal design and implementation patterns
• User docs focus on practical usage and integration
• Clear cross-references between related topics

[Copilot]

Pull Request Overview

This pull request adds comprehensive documentation infrastructure and refactors the Data module's ByteArray representation from Uint8Array to hex strings. The PR introduces Twoslash-powered code examples, documentation generation tooling, and extensive new documentation pages covering wallets, transactions, and client usage.

Key changes:

• Data module refactor: Changed Data.ByteArray from Uint8Array to hex string representation for consistency
• Documentation infrastructure: Added Fumadocs Twoslash integration for interactive TypeScript code examples with type information
• Documentation content: Created comprehensive guides for wallets, transactions, clients, and providers
• Tooling improvements: Enhanced documentation generation scripts with grouping support and skip tags

Reviewed Changes

Copilot reviewed 142 out of 143 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/evolution/src/core/Data.ts	Refactored ByteArray from Uint8Array to hex string representation
packages/evolution/src/core/TSchema.ts	Simplified ByteArray schema to use hex string directly
packages/evolution/test/Data.test.ts	Updated tests to expect hex strings instead of Uint8Array
packages/evolution/src/sdk/wallet/WalletNew.ts	Enhanced documentation with detailed JSDoc comments
packages/evolution/src/sdk/wallet/Wallet.ts	Removed deprecated wallet implementation file
packages/evolution/src/sdk/provider/*.ts	Added comprehensive JSDoc documentation to provider classes
packages/evolution/src/sdk/client/*.ts	Improved documentation and cleaned up implementation comments
docs/package.json	Added Twoslash dependencies for interactive code examples
docs/source.config.ts	Configured Shiki themes and Twoslash transformer
docs/scripts/*.ts	Enhanced documentation generation with grouping and filtering
docs/content/docs/**/*.mdx	Added extensive documentation for wallets, transactions, and providers
pnpm-lock.yaml	Updated dependencies including Twoslash, Mermaid, and related packages

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.