From e7a736e12811d0f1a293fad30e017ad40c0d25cd Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Tue, 25 Nov 2025 00:00:24 +0000
Subject: [PATCH] docs: add CLI reference, PGP examples, and detailed sigil
 list

---
 docs/cli.md               | 116 ++++++++++++++++++++++++++++++++++++++
 docs/index.md             |   5 ++
 docs/pgp.md               |  76 +++++++++++++++++++++++++
 docs/standalone_sigils.md |  15 +++++
 mkdocs.yml                |   2 +
 5 files changed, 214 insertions(+)
 create mode 100644 docs/cli.md
 create mode 100644 docs/pgp.md

diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 0000000..9f6d147
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,116 @@
+# CLI Reference
+
+The `trix` command-line tool allows you to work with `.trix` files, apply sigils, and perform hashing operations directly from the terminal.
+
+## Usage
+
+```bash
+trix [command]
+```
+
+## Global Flags
+
+*   `--help`: Show help for command.
+
+## Commands
+
+### `encode`
+
+Encodes data into the `.trix` file format.
+
+```bash
+trix encode [flags] [sigils...]
+```
+
+**Flags:**
+
+*   `-i, --input string`: Input file path. If not specified, reads from stdin.
+*   `-o, --output string`: Output file path. If not specified, writes to stdout.
+*   `-m, --magic string`: Custom 4-byte magic number (e.g., `TRIX`).
+
+**Example:**
+
+```bash
+# Encode a file, apply gzip and base64 sigils, and save to output.trix
+trix encode -i data.json -o output.trix -m TRIX gzip base64
+```
+
+### `decode`
+
+Decodes a `.trix` file.
+
+```bash
+trix decode [flags] [sigils...]
+```
+
+**Flags:**
+
+*   `-i, --input string`: Input file path. If not specified, reads from stdin.
+*   `-o, --output string`: Output file path. If not specified, writes to stdout.
+*   `-m, --magic string`: Custom 4-byte magic number.
+
+**Example:**
+
+```bash
+# Decode a file, reversing the base64 and gzip sigils implicitly if stored in header,
+# or explicit sigils can be passed if needed for unpacking steps not in header (though unlikely for standard use).
+# Typically:
+trix decode -i output.trix -o restored.json -m TRIX
+```
+
+### `hash`
+
+Hashes input data using a specified algorithm.
+
+```bash
+trix hash [algorithm] [flags]
+```
+
+**Arguments:**
+
+*   `algorithm`: The hash algorithm to use (e.g., `sha256`, `md5`, `lthn`).
+
+**Flags:**
+
+*   `-i, --input string`: Input file path. If not specified, reads from stdin.
+
+**Example:**
+
+```bash
+echo "hello" | trix hash sha256
+```
+
+### Sigil Commands
+
+You can apply individual sigils directly to data.
+
+```bash
+trix [sigil_name] [flags]
+```
+
+**Available Sigils:**
+
+*   `reverse`
+*   `hex`
+*   `base64`
+*   `gzip`
+*   `json`, `json-indent`
+*   `md4`, `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512`
+*   `ripemd160`
+*   `sha3-224`, `sha3-256`, `sha3-384`, `sha3-512`
+*   `sha512-224`, `sha512-256`
+*   `blake2s-256`, `blake2b-256`, `blake2b-384`, `blake2b-512`
+
+**Flags:**
+
+*   `-i, --input string`: Input file or string. Use `-` for stdin.
+
+**Example:**
+
+```bash
+# Base64 encode a string
+trix base64 -i "hello world"
+
+# Gzip a file
+trix gzip -i myfile.txt > myfile.txt.gz
+```
diff --git a/docs/index.md b/docs/index.md
index 4ff9bf4..ef14a74 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,6 +6,10 @@ Enchantrix is a Go-based crypto library and miner application. This documentatio
 
 The `.trix` file format is a generic and flexible binary container for storing an arbitrary data payload alongside structured metadata. For more information, see the [Trix File Format](./trix_format.md) page.
 
+## CLI Reference
+
+Enchantrix provides a command-line tool for encoding, decoding, and hashing data. See the [CLI Reference](./cli.md) for detailed usage instructions.
+
 ## Examples
 
 The following pages provide examples of how to use the Enchantrix library:
@@ -14,4 +18,5 @@ The following pages provide examples of how to use the Enchantrix library:
 *   [Hashing](./hashing.md)
 *   [Checksums](./checksums.md)
 *   [RSA](./rsa.md)
+*   [PGP](./pgp.md)
 *   [Standalone Sigils](./standalone_sigils.md)
diff --git a/docs/pgp.md b/docs/pgp.md
new file mode 100644
index 0000000..1d52291
--- /dev/null
+++ b/docs/pgp.md
@@ -0,0 +1,76 @@
+# PGP
+
+This example demonstrates how to use the `crypt` service to perform PGP operations, including key generation, encryption, decryption, signing, and verification.
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+
+	"github.com/Snider/Enchantrix/pkg/crypt"
+)
+
+func demoPGP() {
+	fmt.Println("--- PGP Demo ---")
+	cryptService := crypt.NewService()
+
+	// 1. Generate PGP Key Pair
+	fmt.Println("Generating PGP key pair...")
+	publicKey, privateKey, err := cryptService.GeneratePGPKeyPair("Alice", "alice@example.com", "Demo Key")
+	if err != nil {
+		log.Fatalf("Failed to generate PGP key pair: %v", err)
+	}
+	fmt.Println("PGP Key pair generated successfully.")
+
+	// 2. Asymmetric Encryption (Public Key Encryption)
+	message := []byte("This is a secret message for PGP.")
+	fmt.Printf("\nOriginal message: %s\n", message)
+
+	encrypted, err := cryptService.EncryptPGP(publicKey, message)
+	if err != nil {
+		log.Fatalf("Failed to encrypt with PGP: %v", err)
+	}
+	fmt.Println("Message encrypted.")
+
+	// 3. Decrypt with Private Key
+	decrypted, err := cryptService.DecryptPGP(privateKey, encrypted)
+	if err != nil {
+		log.Fatalf("Failed to decrypt with PGP: %v", err)
+	}
+	fmt.Printf("Decrypted message: %s\n", decrypted)
+
+	if string(message) == string(decrypted) {
+		fmt.Println("Success! PGP decrypted message matches original.")
+	} else {
+		fmt.Println("Failure! PGP decrypted message does not match.")
+	}
+
+	// 4. Signing and Verification
+	fmt.Println("\n--- PGP Signing Demo ---")
+	signature, err := cryptService.SignPGP(privateKey, message)
+	if err != nil {
+		log.Fatalf("Failed to sign message: %v", err)
+	}
+	fmt.Println("Message signed.")
+
+	err = cryptService.VerifyPGP(publicKey, message, signature)
+	if err != nil {
+		log.Fatalf("Failed to verify signature: %v", err)
+	}
+	fmt.Println("Success! Signature verified.")
+
+	// 5. Symmetric Encryption (Passphrase)
+	fmt.Println("\n--- PGP Symmetric Encryption Demo ---")
+	passphrase := []byte("super-secure-passphrase")
+	symEncrypted, err := cryptService.SymmetricallyEncryptPGP(passphrase, message)
+	if err != nil {
+		log.Fatalf("Failed to symmetrically encrypt: %v", err)
+	}
+	fmt.Println("Message symmetrically encrypted.")
+    // Note: Decryption of symmetrically encrypted PGP messages requires a compatible reader
+    // or usage of the underlying library's features, often handled automatically
+    // if the decryptor prompts for a passphrase.
+}
+```
diff --git a/docs/standalone_sigils.md b/docs/standalone_sigils.md
index 2a03fbc..516343d 100644
--- a/docs/standalone_sigils.md
+++ b/docs/standalone_sigils.md
@@ -2,6 +2,21 @@
 
 This example demonstrates how to use sigils independently to transform data.
 
+## Available Sigils
+
+The `enchantrix` package provides a wide variety of sigils for data transformation and hashing.
+
+| Category | Sigils |
+| :--- | :--- |
+| **Encoding** | `hex`, `base64`, `reverse` |
+| **Compression** | `gzip` |
+| **Formatting** | `json`, `json-indent` |
+| **Standard Hashes** | `md4`, `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512` |
+| **Extended Hashes** | `ripemd160`, `sha3-224`, `sha3-256`, `sha3-384`, `sha3-512`, `sha512-224`, `sha512-256` |
+| **Blake Hashes** | `blake2s-256`, `blake2b-256`, `blake2b-384`, `blake2b-512` |
+
+## Usage Example
+
 ```go
 package main
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 363368d..d744a69 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -9,11 +9,13 @@ theme:
 nav:
   - Home: index.md
   - Trix File Format: trix_format.md
+  - CLI Reference: cli.md
   - Examples:
       - Trix & Sigil Chaining: trix_and_sigils.md
       - Hashing: hashing.md
       - Checksums: checksums.md
       - RSA: rsa.md
+      - PGP: pgp.md
       - Standalone Sigils: standalone_sigils.md
 markdown_extensions:
   - admonition