Docs Audit and Improvements

AUDIT-DOCUMENTATION.md

@@ -0,0 +1,63 @@
+# Documentation Audit Report
+
+This document outlines the findings of a comprehensive documentation audit for the Enchantrix project.
+
+## 1. README Assessment
+
+| Category | Status | Notes |
+| :--- | :--- | :--- |
+| **Project Description** | ✅ Complete | The README provides a clear and concise description of the project's purpose. |
+| **Quick Start** | ✅ Complete | Includes installation and basic usage examples to get started quickly. |
+| **Installation** | ✅ Complete | All necessary installation steps are documented for both the library and the CLI tool. |
+| **Configuration** | ❌ Missing | There is no documentation regarding environment variables or other configuration options. |
+| **Examples** | ✅ Complete | The README contains several clear and useful usage examples. |
+| **Badges** | ✅ Complete | Includes relevant badges for build status, code coverage, Go version, and more. |
+
+## 2. Code Documentation
+
+| Category | Status | Notes |
+| :--- | :--- | :--- |
+| **Function Docs** | ✅ Complete | All public APIs in core packages (`crypt`, `enchantrix`, `trix`) are well-documented. |
+| **Parameter Types** | ✅ Complete | Function signatures are clear, and Go's static typing helps. |
+| **Return Values** | ✅ Complete | Return values are documented in the function comments. |
+| **Examples** | ❌ Missing | GoDoc comments lack runnable examples, which are a standard practice. |
+| **Outdated Docs** | ✅ Up-to-date | The existing documentation appears to be consistent with the current codebase. |
+
+## 3. Architecture Documentation
+
+| Category | Status | Notes |
+| :--- | :--- | :--- |
+| **System Overview** | ✅ Complete | The `rfcs` directory provides a good high-level overview of the system architecture. |
+| **Data Flow** | ✅ Complete | The RFCs explain how data moves through the system. |
+| **Component Diagram** | ❌ Missing | A visual component diagram would be a valuable addition to the architectural documentation. |
+| **Decision Records** | ✅ Complete | The RFCs serve as Architecture Decision Records (ADRs). |
+
+## 4. Developer Documentation
+
+| Category | Status | Notes |
+| :--- | :--- | :--- |
+| **Contributing Guide** | ❌ Missing | There is no `CONTRIBUTING.md` file to guide potential contributors. |
+| **Development Setup** | ✅ Complete | The README provides sufficient information for setting up a local development environment. |
+| **Testing Guide** | ✅ Complete | The README explains how to run the test suite. |
+| **Code Style** | ❌ Missing | There is no documented code style guide, although the project appears to follow standard Go formatting. |
+
+## 5. User Documentation
+
+| Category | Status | Notes |
+| :--- | :--- | :--- |
+| **User Guide** | ✅ Complete | The `docs` directory contains a comprehensive user guide. |
+| **FAQ** | ❌ Missing | There is no Frequently Asked Questions (FAQ) section. |
+| **Troubleshooting** | ❌ Missing | There is no dedicated troubleshooting guide for common issues. |
+| **Changelog** | ❌ Missing | There is no `CHANGELOG.md` file to track changes between versions. |
+
+## Summary of Documentation Gaps
+
+Based on this audit, the following documentation gaps have been identified:
+
+1.  **`CONTRIBUTING.md`:** A guide for contributors is missing.
+2.  **`CHANGELOG.md`:** A version history is needed.
+3.  **FAQ & Troubleshooting:** The user documentation would benefit from dedicated sections for common questions and issues.
+4.  **Runnable GoDoc Examples:** The code documentation should include runnable examples.
+5.  **Architecture Diagram:** A visual diagram would improve the architecture documentation.
+6.  **Configuration Documentation:** Information on environment variables or other configuration is missing.
+7.  **Code Style Guide:** A formal code style guide is not present.

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of the Enchantrix library.
+- `crypt` package for hashing, checksums, RSA, and PGP operations.
+- `enchantrix` package for the Sigil transformation framework.
+- `trix` package for the .trix binary container format.
+- `trix` command-line tool for encoding, decoding, and transformations.
+- RFCs for core protocols.
+- MkDocs documentation site.

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to Enchantrix
+
+First off, thank you for considering contributing to Enchantrix! It's people like you that make open source such a great community.
+
+## Where do I go from here?
+
+If you've noticed a bug or have a feature request, [make one](https://github.com/Snider/Enchantrix/issues/new)! It's generally best if you get confirmation of your bug or approval for your feature request this way before starting to code.
+
+### Fork & create a branch
+
+If this is something you think you can fix, then [fork Enchantrix](https://github.com/Snider/Enchantrix/fork) and create a branch with a descriptive name.
+
+A good branch name would be (where issue #38 is the ticket you're working on):
+
+```sh
+git checkout -b 38-add-awesome-new-feature
+```
+
+## Getting started
+
+### Development Environment
+
+To get started with development, you'll need to have Go 1.25 installed on your system, as specified in the `go.mod` file. You can download it from the official [Go website](https://go.dev/dl/).
+
+Once you have Go installed, you can clone your fork of the repository:
+
+```sh
+git clone https://github.com/YOUR_USERNAME/Enchantrix.git
+cd Enchantrix
+```
+
+### Running Tests
+
+Enchantrix uses the standard Go testing tools. To run all tests, use the following command from the root of the repository:
+
+```sh
+go test ./...
+```
+
+To run tests with race detection, which is recommended:
+
+```sh
+go test -race ./...
+```
+
+To generate a coverage report:
+
+```sh
+go test -coverprofile=coverage.out ./...
+```
+
+## Code Style
+
+This project follows standard Go coding conventions. Please ensure your code is formatted with `gofmt` before submitting a pull request. Most IDEs can be configured to do this automatically on save.
+
+```sh
+gofmt -w .
+```
+
+## Submitting a Pull Request
+
+When you're ready to submit a pull request, please make sure you do the following:
+
+1.  **Write tests.** Your patch won't be accepted if it doesn't have tests.
+2.  **Follow the style guide.** Your code should be formatted with `gofmt`.
+3.  **Write a good commit message.** A good commit message should be descriptive and concise.
+4.  **Push to your fork** and submit a pull request.
+5.  **Ensure the test suite passes.** The CI pipeline will run the tests, and your PR will not be merged if the tests are failing.
+
+We'll review your pull request as soon as possible. We may suggest some changes or improvements or approve it as is.

docs/faq.md

@@ -0,0 +1,23 @@
+# Frequently Asked Questions (FAQ)
+
+This page answers some of the most common questions about Enchantrix.
+
+## General
+
+### What is the purpose of the .trix container format?
+
+The .trix format is a generic binary container designed to hold a payload and associated metadata. It is protocol-agnostic, meaning it can be used to store any type of data. Its primary purpose is to provide a flexible and extensible format for data that may need to be transformed or encrypted.
+
+### What are Sigils?
+
+Sigils are the core concept of the Enchantrix transformation framework. Each Sigil represents a single, reversible data transformation, such as encoding, compression, or hashing. They can be chained together to create powerful and flexible transformation pipelines.
+
+## Development
+
+### How do I add a new Sigil?
+
+To add a new Sigil, you need to create a new struct that implements the `enchantrix.Sigil` interface. This involves implementing the `In()` and `Out()` methods. Once your Sigil is implemented, you can add it to the `enchantrix.NewSigil()` factory function.
+
+### Can I use my own magic number for the .trix format?
+
+Yes, the `trix.Encode()` and `trix.Decode()` functions accept a custom 4-byte magic number string. This allows you to create your own application-specific file formats based on the .trix container.

docs/troubleshooting.md

@@ -0,0 +1,31 @@
+# Troubleshooting
+
+This page provides solutions to common problems you might encounter while using Enchantrix.
+
+## CLI
+
+### `command not found: trix`
+
+This error means that the `trix` binary is not in your system's `PATH`. When you install Go binaries with `go install`, they are placed in the `GOBIN` directory, which is typically `$GOPATH/bin`.
+
+To fix this, you need to add your Go binary path to your shell's `PATH` variable. Add the following line to your shell's configuration file (e.g., `~/.bashrc`, `~/.zshrc`):
+
+```sh
+export PATH=$PATH:$(go env GOPATH)/bin
+```
+
+Then, restart your shell or source the configuration file for the changes to take effect.
+
+## Library
+
+### `trix: invalid magic number`
+
+This error occurs when you try to decode a `.trix` file with a magic number that does not match the one that was used to encode it. The magic number is a 4-byte string that acts as a file format identifier.
+
+To fix this, ensure that you are using the same magic number for both `trix.Encode()` and `trix.Decode()`.
+
+### `trix: checksum mismatch`
+
+This error indicates that the payload of the `.trix` container has been corrupted or altered since it was created. The checksum is a hash of the payload that is stored in the header to verify data integrity.
+
+If you encounter this error, the data you are trying to read is not the same as the data that was originally written.

mkdocs.yml

@@ -17,6 +17,8 @@ nav:
       - RSA: rsa.md
       - PGP: pgp.md
       - Standalone Sigils: standalone_sigils.md
+  - FAQ: faq.md
+  - Troubleshooting: troubleshooting.md
 markdown_extensions:
   - admonition
   - codehilite