final corrections

CBT-Format.md

@@ -0,0 +1,189 @@
+# CBT File Format
+
+## Overview
+
+**CBT** (Comic Book TAR) is a comic book archive format that uses TAR (Tape Archive) as the container format instead of ZIP. Gopherbook supports both unencrypted and AES-256 encrypted CBT files.
+
+## Format Specification
+
+### Basic Structure
+
+A CBT file is simply a TAR archive containing:
+- Image files (JPEG, PNG, GIF, AVIF, JXL, WebP, BMP, JP2)
+- `ComicInfo.xml` (optional metadata)
+
+### File Extensions
+
+- `.cbt` - Standard CBT file
+
+### Supported Image Formats
+
+- `.jpg`, `.jpeg` - JPEG images
+- `.png` - PNG images
+- `.gif` - GIF images
+- `.avif` - AVIF images
+- `.jxl` - JPEG XL images
+- `.webp` - WebP images
+- `.bmp` - Bitmap images
+- `.jp2` - JPEG 2000 images
+
+## Encryption
+
+### Encryption Method
+
+Gopherbook uses **AES-256-CFB** (Cipher Feedback mode) for encryption:
+
+1. **Key Derivation**: SHA-256 hash of the password
+2. **IV Generation**: Random 16-byte initialization vector
+3. **Encryption**: AES-256-CFB on the entire TAR archive
+4. **Storage**: IV prepended to ciphertext
+
+### Encrypted File Structure
+
+```
+[16 bytes IV][Encrypted TAR data...]
+```
+
+### Compatibility
+
+The encryption format is compatible with:
+- OpenSSL command-line tools
+- Gopherbook's Go implementation
+- The provided bash script (`cbt.sh`)
+
+## ComicInfo.xml
+
+CBT files can include a `ComicInfo.xml` file for metadata. Gopherbook extracts:
+
+- **Title** - Comic title
+- **Series** - Series name
+- **Number** - Issue number
+- **Writer** - Writer name
+- **Artist** / **Inker** - Artist name
+- **Publisher** - Publisher name
+- **Genre** / **Tags** - Tags/genres
+- **StoryArc** - Story arc name
+- **Year** - Publication year
+- **Month** - Publication month
+- **Summary** - Description
+- **PageCount** - Number of pages
+
+### Example ComicInfo.xml
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<ComicInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <Title>The Amazing Adventure</Title>
+    <Series>Super Comics</Series>
+    <Number>42</Number>
+    <Writer>John Doe</Writer>
+    <Artist>Jane Smith</Artist>
+    <Publisher>Comic Press</Publisher>
+    <Genre>Action, Adventure</Genre>
+    <Tags>superhero, action</Tags>
+    <StoryArc>The Grand Quest</StoryArc>
+    <Year>2024</Year>
+    <Month>1</Month>
+    <Summary>An epic tale of heroism...</Summary>
+    <PageCount>24</PageCount>
+</ComicInfo>
+```
+
+## CBT vs CBZ
+
+### Advantages of CBT
+
+1. **Simpler Format**: TAR is simpler than ZIP
+2. **Better for Streaming**: Sequential structure
+3. **Unix-Friendly**: Native TAR tools on all Unix systems
+4. **Compression Agnostic**: Images already compressed
+
+### Advantages of CBZ
+
+1. **More Common**: Wider software support
+2. **Per-File Compression**: Can compress text metadata
+3. **Random Access**: Easier to extract single files
+
+### When to Use CBT
+
+- Unix/Linux environments
+- Streaming applications
+- Encrypted archives (simpler encryption)
+- Archival purposes
+
+### When to Use CBZ
+
+- Windows environments
+- Maximum compatibility
+- Need per-file compression
+- Most comic readers
+
+## Creating CBT Files
+
+See the [Creating CBT Files](Creating-CBT-Files) page for detailed instructions using:
+- The `cbt.sh` bash script
+- The `cbt.go` Go program
+- Manual TAR commands
+
+## Technical Details
+
+### Encryption Algorithm Details
+
+```
+Algorithm: AES-256-CFB
+Key: SHA256(password) = 32 bytes
+IV: Random 16 bytes
+Block Size: 16 bytes (128 bits)
+Mode: CFB (Cipher Feedback)
+```
+
+### Decryption Process
+
+1. Read first 16 bytes as IV
+2. Read remaining bytes as ciphertext
+3. Derive key from password using SHA-256
+4. Decrypt using AES-256-CFB with IV and key
+5. Extract TAR archive from plaintext
+
+### Validation
+
+To check if a CBT is encrypted:
+
+```bash
+# Try reading as TAR
+tar -tf file.cbt
+
+# If it fails, likely encrypted
+# If it succeeds, unencrypted
+```
+
+## File Organization
+
+Gopherbook automatically organizes CBT files:
+
+```
+library/
+└── [Artist]/
+    └── [StoryArc]/
+        └── comic.cbt
+```
+
+Based on extracted metadata from ComicInfo.xml.
+
+## Best Practices
+
+1. **Always include ComicInfo.xml** for proper metadata
+2. **Use consistent naming** for images (001.jpg, 002.jpg, etc.)
+3. **Encrypt sensitive content** using strong passwords
+4. **Store passwords securely** (Gopherbook does this automatically)
+5. **Backup your library** regularly
+
+## Related Pages
+
+- [Creating CBT Files](Creating-CBT-Files)
+- [Bash Scripts](Bash-Scripts)
+- [Password Protection](Password-Protection)
+
+---
+
+**Note**: CBT support is a unique feature of Gopherbook. Most comic readers only support CBZ/CBR formats.

Creating-CBT-Files.md

@@ -0,0 +1,332 @@
+# Creating CBT Files
+
+This guide covers multiple methods for creating CBT (Comic Book TAR) files with or without encryption.
+
+## Method 1: Using the cbt.sh Bash Script (Recommended)
+
+### Prerequisites
+
+- Bash shell (Linux/Mac/WSL)
+- OpenSSL
+- Standard Unix tools (tar, sha256sum, xxd)
+
+### Installation
+
+The `cbt.sh` script is included in the `scripts-bash/comic-scripts/` directory:
+
+```bash
+chmod +x scripts-bash/comic-scripts/cbt.sh
+```
+
+### Creating Unencrypted CBT
+
+```bash
+./scripts-bash/comic-scripts/cbt.sh create -i /path/to/comic/images -o mycomic.cbt
+```
+
+**Example:**
+```bash
+./scripts-bash/comic-scripts/cbt.sh create -i ./my-comic-pages-folder -o amazing-comic.cbt
+```
+
+This will:
+1. Create a TAR archive from all files in the directory
+2. Save it as `amazing-comic.cbt`
+3. Display list of files added
+
+### Creating Encrypted CBT
+
+```bash
+./scripts-bash/comic-scripts/cbt.sh create -i /path/to/comic/images -o mycomic.cbt -p "your-password"
+```
+
+**Example:**
+```bash
+./scripts-bash/comic-scripts/cbt.sh create -i ./my-comic-pages-folder -o secret-comic.cbt -p "super-secret-123"
+```
+
+This will:
+1. Create a TAR archive
+2. Encrypt it using AES-256-CFB
+3. Save the encrypted CBT file
+
+### Extracting CBT Files
+
+**Unencrypted:**
+```bash
+./scripts-bash/comic-scripts/cbt.sh extract -i mycomic.cbt -o ./extracted
+```
+
+**Encrypted:**
+```bash
+./scripts-bash/comic-scripts/cbt.sh extract -i secret-comic.cbt -o ./extracted -p "your-password"
+```
+
+### Script Options
+
+```
+Usage:
+  Create:  cbt.sh create -i <input_directory> -o <output_file> [-p <password>]
+  Extract: cbt.sh extract -i <input_file> -o <output_directory> [-p <password>]
+
+Options:
+  -i    Input directory/file
+  -o    Output file/directory
+  -p    Password for encryption/decryption (optional)
+```
+
+## Method 2: Using the cbt.go Program
+
+### Prerequisites
+
+- Go 1.25.2 or higher
+
+### Building the Tool
+
+```bash
+cd tools/cbt-creator
+go build -o cbt scripts-go/cbt.go
+```
+
+### Creating Unencrypted CBT
+
+```bash
+./cbt -input /path/to/images -output mycomic.cbt
+```
+
+**Example:**
+```bash
+./cbt -input ./comic-pages-folder -output "My Amazing Comic.cbt"
+```
+
+### Creating Encrypted CBT
+
+```bash
+./cbt -input /path/to/images -output mycomic.cbt -password "your-password"
+```
+
+**Example:**
+```bash
+./cbt -input ./comic-pages-folder -output "Secret Comic.cbt" -password "super-secret-123"
+```
+
+### Program Options
+
+```
+Usage: cbt -input <directory> -output <file.cbt> [-password <password>]
+
+Flags:
+  -input string
+        Input directory containing comic files
+  -output string
+        Output .cbt file
+  -password string
+        Password for encryption (leave empty for no encryption)
+```
+
+## Method 3: Manual Creation with TAR
+
+### Creating Unencrypted CBT
+
+```bash
+cd /path/to/comic/images
+tar -cf ../mycomic.cbt *
+```
+
+### Creating Encrypted CBT Manually
+
+1. **Create TAR archive:**
+   ```bash
+   tar -cf temp.tar *
+   ```
+
+2. **Encrypt using OpenSSL:**
+   ```bash
+   # Generate key from password
+   KEY=$(echo -n "your-password" | sha256sum | cut -d' ' -f1)
+   
+   # Generate random IV
+   openssl rand -out iv.bin 16
+   
+   # Encrypt
+   openssl enc -aes-256-cfb -K "$KEY" -iv $(xxd -p -c 256 iv.bin) -in temp.tar -out temp.enc
+   
+   # Combine IV and encrypted data
+   cat iv.bin temp.enc > mycomic.cbt
+   
+   # Cleanup
+   rm temp.tar iv.bin temp.enc
+   ```
+
+## Directory Structure Best Practices
+
+### Recommended Structure
+
+```
+comic-pages/
+├── 001.jpg
+├── 002.jpg
+├── 003.jpg
+├── ...
+└── ComicInfo.xml
+```
+
+### File Naming
+
+Use zero-padded numbers for proper sorting:
+- ✅ `001.jpg`, `002.jpg`, `003.jpg`
+- ❌ `1.jpg`, `2.jpg`, `3.jpg`
+
+### Including ComicInfo.xml
+
+Always include metadata for best results:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<ComicInfo>
+    <Title>My Comic Title</Title>
+    <Series>My Series</Series>
+    <Number>1</Number>
+    <Writer>Author Name</Writer>
+    <Artist>Artist Name</Artist>
+    <Publisher>Publisher</Publisher>
+    <Genre>Action, Adventure</Genre>
+    <Year>2024</Year>
+    <PageCount>24</PageCount>
+</ComicInfo>
+```
+
+## Automated Workflow Scripts
+
+### Batch Creation Script
+
+Create `batch-cbt.sh`:
+
+```bash
+#!/bin/bash
+
+PASSWORD="your-default-password"
+
+for dir in */; do
+    dirname="${dir%/}"
+    echo "Processing: $dirname"
+    ./cbt.sh create -i "$dir" -o "${dirname}.cbt" -p "$PASSWORD"
+done
+
+echo "Batch creation complete!"
+```
+
+Usage:
+```bash
+chmod +x batch-cbt.sh
+./batch-cbt.sh
+```
+
+### Using with GPG-Encrypted Passwords
+
+Store passwords securely with GPG:
+
+```bash
+#!/bin/bash
+
+# Store password encrypted
+echo "my-secret-password" | gpg -e -r your@email.com > password.gpg
+
+# Use in script
+PASSWORD=$(gpg -qd password.gpg)
+./cbt.sh create -i ./comic -o comic.cbt -p "$PASSWORD"
+```
+
+## Testing Your CBT Files
+
+### Test with Gopherbook
+
+1. Upload to Gopherbook via web UI
+2. Or place in watch folder:
+   ```bash
+   cp mycomic.cbt ./watch/[username]/
+   ```
+
+### Test Encryption
+
+```bash
+# Should fail if encrypted
+tar -tf mycomic.cbt
+
+# Should succeed if unencrypted
+tar -tf mycomic.cbt
+```
+
+### Test Extraction
+
+```bash
+./cbt.sh extract -i mycomic.cbt -o test-extract -p "password"
+ls test-extract/
+```
+
+## Integration with Comic Creation Tools
+
+### ImageMagick Conversion
+
+Convert PDF or images to comic pages:
+
+```bash
+# Convert PDF to images
+magick convert -density 300 comic.pdf page-%03d.jpg
+
+# Create CBT
+./cbt.sh create -i . -o comic.cbt
+```
+
+### Optimize Images Before Packing
+
+```bash
+# Optimize JPEGs
+for img in *.jpg; do
+    mogrify -quality 85 -strip "$img"
+done
+
+# Create optimized CBT
+./cbt.sh create -i . -o optimized-comic.cbt -p "password"
+```
+
+## Troubleshooting
+
+### "Permission Denied" Error
+
+```bash
+chmod +x scripts-bash/cbt.sh
+```
+
+### "Command Not Found" Errors
+
+Ensure required tools are installed:
+```bash
+# Ubuntu/Debian
+sudo apt install tar openssl xxd coreutils
+
+# Fedora
+sudo dnf install tar openssl vim-common coreutils
+
+# macOS
+brew install gnu-tar openssl
+```
+
+### Encryption Issues
+
+Verify OpenSSL version:
+```bash
+openssl version
+```
+
+Should be OpenSSL 1.1.1 or higher.
+
+## Related Pages
+
+- [CBT File Format](CBT-Format) - Technical details
+- [Bash Scripts](Bash-Scripts) - All available scripts
+- [Password Protection](Password-Protection) - Security features
+
+---
+
+**Tip**: Use the bash script for simplicity, or the Go program for cross-platform compatibility.