From 378fc7c0dea7a938c3610174f847c1a03a1f3c97 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Tue, 31 Mar 2026 07:24:17 +0000
Subject: [PATCH] docs(ax): align sigil references with current surfaces

Co-Authored-By: Virgil <virgil@lethean.io>
---
 CLAUDE.md            |  2 +-
 docs/RFC.md          | 44 +++++++++++++++++---------------------------
 docs/architecture.md |  4 ++--
 3 files changed, 20 insertions(+), 30 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index abe2112..9c63220 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -128,7 +128,7 @@ Backend packages use `var _ io.Medium = (*Medium)(nil)` to verify interface comp
 
 ### Sentinel Errors
 
-Sentinel errors (`var ErrNotFound`, `var ErrInvalidKey`, etc.) use standard `errors.New()` — this is correct Go convention. Only inline error returns in functions should use `coreerr.E()`.
+Sentinel errors (`var NotFoundError`, `var InvalidKeyError`, etc.) use standard `errors.New()` — this is correct Go convention. Only inline error returns in functions should use `coreerr.E()`.
 
 ## Testing
 
diff --git a/docs/RFC.md b/docs/RFC.md
index 3fab450..adcbe42 100644
--- a/docs/RFC.md
+++ b/docs/RFC.md
@@ -2341,45 +2341,45 @@ Example:
 s, _ := sigil.NewSigil("hex")
 ```
 
-### ErrInvalidKey
+### InvalidKeyError
 
 Returned when an encryption key is not 32 bytes.
 
 Example:
 ```go
-_, err := sigil.NewChaChaPolySigil([]byte("short"))
-if errors.Is(err, sigil.ErrInvalidKey) {
+_, err := sigil.NewChaChaPolySigil([]byte("short"), nil)
+if errors.Is(err, sigil.InvalidKeyError) {
 	// handle invalid key
 }
 ```
 
-### ErrCiphertextTooShort
+### CiphertextTooShortError
 
 Returned when ciphertext is too short to decrypt.
 
 Example:
 ```go
 _, err := sigil.GetNonceFromCiphertext([]byte("short"))
-if errors.Is(err, sigil.ErrCiphertextTooShort) {
+if errors.Is(err, sigil.CiphertextTooShortError) {
 	// handle truncated payload
 }
 ```
 
-### ErrDecryptionFailed
+### DecryptionFailedError
 
 Returned when decryption or authentication fails.
 
 Example:
 ```go
 key := make([]byte, 32)
-s, _ := sigil.NewChaChaPolySigil(key)
+s, _ := sigil.NewChaChaPolySigil(key, nil)
 _, err := s.Out([]byte("tampered"))
-if errors.Is(err, sigil.ErrDecryptionFailed) {
+if errors.Is(err, sigil.DecryptionFailedError) {
 	// handle failed decrypt
 }
 ```
 
-### ErrNoKeyConfigured
+### NoKeyConfiguredError
 
 Returned when a `ChaChaPolySigil` has no key.
 
@@ -2387,7 +2387,7 @@ Example:
 ```go
 s := &sigil.ChaChaPolySigil{}
 _, err := s.In([]byte("data"))
-if errors.Is(err, sigil.ErrNoKeyConfigured) {
+if errors.Is(err, sigil.NoKeyConfiguredError) {
 	// handle missing key
 }
 ```
@@ -2472,14 +2472,14 @@ XChaCha20-Poly1305 encryption sigil with optional pre-obfuscation.
 Example:
 ```go
 key := make([]byte, 32)
-s, _ := sigil.NewChaChaPolySigil(key)
+s, _ := sigil.NewChaChaPolySigil(key, nil)
 ```
 
 **In(data []byte) ([]byte, error)**
 Example:
 ```go
 key := make([]byte, 32)
-s, _ := sigil.NewChaChaPolySigil(key)
+s, _ := sigil.NewChaChaPolySigil(key, nil)
 ciphertext, _ := s.In([]byte("hello"))
 ```
 
@@ -2487,30 +2487,20 @@ ciphertext, _ := s.In([]byte("hello"))
 Example:
 ```go
 key := make([]byte, 32)
-s, _ := sigil.NewChaChaPolySigil(key)
+s, _ := sigil.NewChaChaPolySigil(key, nil)
 ciphertext, _ := s.In([]byte("hello"))
 plain, _ := s.Out(ciphertext)
 ```
 
-### NewChaChaPolySigil(key []byte) (*ChaChaPolySigil, error)
+### NewChaChaPolySigil(key []byte, obfuscator PreObfuscator) (*ChaChaPolySigil, error)
 
-Creates an encryption sigil with the default XOR obfuscator.
-
-Example:
-```go
-key := make([]byte, 32)
-s, _ := sigil.NewChaChaPolySigil(key)
-```
-
-### NewChaChaPolySigilWithObfuscator(key []byte, obfuscator PreObfuscator) (*ChaChaPolySigil, error)
-
-Creates an encryption sigil with a custom obfuscator.
+Creates an encryption sigil with an optional pre-obfuscator. Pass `nil` to use the default XOR obfuscator.
 
 Example:
 ```go
 key := make([]byte, 32)
 ob := &sigil.ShuffleMaskObfuscator{}
-s, _ := sigil.NewChaChaPolySigilWithObfuscator(key, ob)
+s, _ := sigil.NewChaChaPolySigil(key, ob)
 ```
 
 ### GetNonceFromCiphertext(ciphertext []byte) ([]byte, error)
@@ -2520,7 +2510,7 @@ Extracts the XChaCha20 nonce from encrypted output.
 Example:
 ```go
 key := make([]byte, 32)
-s, _ := sigil.NewChaChaPolySigil(key)
+s, _ := sigil.NewChaChaPolySigil(key, nil)
 ciphertext, _ := s.In([]byte("hello"))
 nonce, _ := sigil.GetNonceFromCiphertext(ciphertext)
 ```
diff --git a/docs/architecture.md b/docs/architecture.md
index 8db0246..f6df154 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -230,12 +230,12 @@ The pre-obfuscation layer ensures that raw plaintext patterns are never sent dir
 key := make([]byte, 32)
 rand.Read(key)
 
-s, _ := sigil.NewChaChaPolySigil(key)
+s, _ := sigil.NewChaChaPolySigil(key, nil)
 ciphertext, _ := s.In([]byte("secret"))
 plaintext, _ := s.Out(ciphertext)
 
 // With stronger obfuscation:
-s2, _ := sigil.NewChaChaPolySigilWithObfuscator(key, &sigil.ShuffleMaskObfuscator{})
+s2, _ := sigil.NewChaChaPolySigil(key, &sigil.ShuffleMaskObfuscator{})
 ```
 
 Each call to `In` generates a fresh random nonce, so encrypting the same plaintext twice produces different ciphertexts.