diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..6c2d184
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Test Commands
+
+```shell
+# Run all tests with coverage
+go test -v -coverprofile=coverage.out ./...
+
+# Run a single test
+go test -v -run TestName ./pkg/enchantrix
+
+# Run tests with race detection (as CI does)
+go test -race -coverprofile=coverage.out -covermode=atomic ./...
+
+# Run fuzz tests (CI runs 10s)
+go test -run=Fuzz -fuzz=Fuzz -fuzztime=10s ./pkg/trix
+
+# Build
+go build -v ./...
+
+# Vet
+go vet ./...
+
+# Format
+go fmt ./...
+```
+
+If Task is installed, these are available:
+- `task test` - Run tests with coverage
+- `task build` - Build project
+- `task fmt` - Format code
+- `task vet` - Run go vet
+
+## Architecture
+
+Enchantrix is an encryption library with a custom `.trix` file format and CLI tool.
+
+### Core Packages
+
+**pkg/enchantrix** - Core transformation framework
+- `Sigil` interface: defines `In(data)` and `Out(data)` for reversible/irreversible transforms
+- `Transmute()`: applies a chain of sigils to data
+- Built-in sigils: `reverse`, `hex`, `base64`, `gzip`, `json`, `json-indent`
+- Hash sigils: `md4`, `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512`, `ripemd160`, `sha3-*`, `sha512-*`, `blake2s-256`, `blake2b-*`
+- `NewSigil(name)`: factory function to create sigils by string name
+- `ChaChaPolySigil`: encryption sigil using XChaCha20-Poly1305 with pre-obfuscation layer
+
+**pkg/trix** - Binary file format (.trix)
+- Format: `[4-byte magic][1-byte version][4-byte header len][JSON header][payload]`
+- `Encode()`: serializes Trix struct to binary
+- `Decode()`: deserializes binary to Trix struct
+- `Pack()`/`Unpack()`: apply/reverse sigils on payload
+- Supports optional checksums via `ChecksumAlgo` field
+
+**pkg/crypt** - Cryptographic services facade
+- `Service`: aggregates hashing, checksums, RSA, and PGP operations
+- Hash types: `lthn` (custom), `sha512`, `sha256`, `sha1`, `md5`
+- Checksums: `Luhn()`, `Fletcher16/32/64()`
+- RSA: key generation, encrypt/decrypt via `pkg/crypt/std/rsa`
+- PGP: key generation, encrypt/decrypt, sign/verify, symmetric encrypt via `pkg/crypt/std/pgp`
+
+**cmd/trix** - CLI tool (Cobra-based)
+- `trix encode --magic XXXX --output file [sigils...]`
+- `trix decode --magic XXXX --output file [sigils...]`
+- `trix hash [algorithm]`
+- `trix [sigil]` - apply any sigil directly
+
+### Key Design Patterns
+
+1. **Sigil Chain**: Transformations are composable. Encoding chains sigils in order; decoding reverses.
+2. **Pre-Obfuscation**: `ChaChaPolySigil` applies XOR or shuffle-mask obfuscation before encryption so raw plaintext never goes directly to CPU encryption routines.
+3. **Streaming Support**: `Encode()`/`Decode()` accept optional `io.Writer`/`io.Reader` for streaming.
+
+## Testing Conventions
+
+- Tests use `testify/assert` and `testify/require`
+- Test files follow `*_test.go` pattern adjacent to implementation
+- `examples_test.go` files contain example functions for godoc
+- Fuzz tests exist in `pkg/trix` (`go test -fuzz`)
+
+## Go Version
+
+Minimum Go 1.25. Uses `go.work` for workspace management.
diff --git a/go.work.sum b/go.work.sum
index 69e4ecb..4eaa30c 100644
--- a/go.work.sum
+++ b/go.work.sum
@@ -1,4 +1,7 @@
+github.com/bwesterb/go-ristretto v1.2.3 h1:1w53tCkGhCQ5djbat3+MH0BAQ5Kfgbt56UZQ/JMzngw=
 github.com/bwesterb/go-ristretto v1.2.3/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
+github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 golang.org/x/net v0.45.0 h1:RLBg5JKixCy82FtLJpeNlVM0nrSqpCRYzVU1n8kj0tM=