diff --git a/README.md b/README.md
index cb8f11c..2494a15 100644
--- a/README.md
+++ b/README.md
@@ -1,665 +1,72 @@
-# Hardware Report: Automated Infrastructure Discovery Tool
+[![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge&logo=rust&logoColor=white)](https://www.rust-lang.org) [![Nix](https://img.shields.io/badge/nix-%23000000.svg?style=for-the-badge&logo=nixos&logoColor=white)](https://nixos.org) [![Linux](https://img.shields.io/badge/linux-%23000000.svg?style=for-the-badge&logo=linux&logoColor=white)](https://kernel.org)
 
-## Executive Summary
+# Hardware Report
 
-**Hardware Report** is a Rust-based utility that automatically discovers, catalogs, and reports detailed hardware information from Linux servers. The tool generates standardized TOML reports that enable consistent infrastructure management across heterogeneous bare-metal hardware environments.
+**Automated infrastructure discovery tool built with hexagonal architecture.**
 
-### Business Value
-- **Infrastructure Standardization**: Uniform hardware inventory across diverse server configurations
-- **Operational Efficiency**: Automated discovery eliminates manual hardware auditing
-- **Scalability**: Generates unique reports per server using chassis serial numbers
-- **Cost Management**: Enables better capacity planning and resource allocation
-- **Compliance**: Provides detailed audit trails for hardware configurations
+Generates structured hardware inventory reports in TOML/JSON format. Designed for CMDB population, infrastructure auditing, and bare-metal server management at scale.
 
-### Target Use Cases
-- GPU compute clusters and AI/ML infrastructure
-- Heterogeneous bare-metal server environments
-- Data center inventory management
-- Infrastructure compliance and auditing
-- Capacity planning and resource optimization
+**Platforms:** Linux, macOS | **Architectures:** x86_64, ARM64 | **GPUs:** NVIDIA (including Blackwell)
 
----
-
-## Technical Overview
-
-### Core Capabilities
-The tool provides comprehensive system discovery including:
-
-**CPU Architecture**
-- Model information and socket configuration
-- Core, thread, and NUMA topology mapping
-- Per-socket core counts and threading details
-
-**Memory Subsystem**
-- Total capacity and module-level details
-- Memory type, speed, and slot mapping
-- Individual DIMM information
-
-**Storage Infrastructure**
-- Device enumeration with capacity and models
-- Filesystem information and mount points
-- Storage type identification (NVMe, SSD, HDD)
-
-**GPU Resources**
-- NVIDIA GPU detection and configuration
-- Memory capacity and PCI topology
-- Device UUID tracking
-
-**Network Infrastructure**
-- Interface discovery with speed capabilities
-- MAC address and IP configuration
-- InfiniBand and high-speed networking support
-
-**System Information**
-- BIOS and firmware details
-- BMC (Baseboard Management Controller) data
-- Chassis and motherboard specifications
-- NUMA topology with device affinity mapping
-
-### Output Format
-Reports are generated as structured TOML files named `<chassis_serial>_hardware_report.toml`, ensuring unique identification and preventing data collisions in large deployments.
-
----
-
-## Quick Start Guide
-
-### Option 1: Nix Build (Recommended)
-
-**One-Line Installation with Nix**
-```bash
-# Install Nix, build, and run in one command:
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install && \
-. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh && \
-git clone https://github.com/sfcompute/hardware_report.git && \
-cd hardware_report && \
-nix build && \
-echo "Build complete! Run with: sudo ./result/bin/hardware_report" && \
-sudo ./result/bin/hardware_report
-```
-
-
-**Interactive Development with Nix (One-Liner Setup)**
+## Table of Contents
 
+- [What Does This Do?](#what-does-this-do)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
 
-```bash
-# Install Nix, activate it, clone the repo, enter the dev shell, and build
-curl --proto '=https' --tlsv1.2 -sSf https://install.determinate.systems/nix | sh -s -- install && \
-. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh && \
-git clone https://github.com/sfcompute/hardware_report.git && \
-cd hardware_report && \
-nix develop && \
-cargo build --release && \
-sudo ./target/release/hardware_report
-```
-
-**Production Deployment (Debian Package with Nix)**
-```bash
-# Build and install system-wide package:
-curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install && \
-. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh && \
-git clone https://github.com/sfcompute/hardware_report.git && \
-cd hardware_report && \
-nix build .#deb && \
-sudo apt --fix-broken install -y && \
-sudo apt remove -y hardware-report 2>/dev/null || true && \
-sudo apt install -y ./result/hardware-report_0.1.7_amd64.deb && \
-sudo hardware_report
-```
+## What Does This Do?
 
-### Option 2: Traditional Build (No Nix Required)
+- **CPU Discovery** - Model, sockets, cores, threads, NUMA topology, cache hierarchy
+- **Memory Detection** - Total capacity, module details, DDR type, speed, slot mapping
+- **Storage Enumeration** - NVMe/SSD/HDD detection, capacity, serial numbers, SMART status
+- **GPU Detection** - NVIDIA via nvidia-smi, memory, PCI topology, UUIDs
+- **Network Interfaces** - MAC/IP, speed (1G-400G+), InfiniBand, driver info
+- **System Information** - BIOS, BMC/IPMI, chassis serial, motherboard specs
 
-**Ubuntu/Debian Systems**
-```bash
-# 1. Install Rust toolchain (if not already installed)
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-source ~/.cargo/env
-
-# 2. Install build dependencies
-sudo apt-get update && sudo apt-get install -y \
-  build-essential \
-  pkg-config \
-  libssl-dev \
-  git
-
-# 3. Install runtime dependencies
-sudo apt-get install -y \
-  numactl \
-  ipmitool \
-  ethtool \
-  util-linux \
-  pciutils
-
-# 4. Clone and build
-git clone https://github.com/sfcompute/hardware_report.git
-cd hardware_report
-cargo build --release
+## Quick Start
 
-# 5. Run the tool
-sudo ./target/release/hardware_report
-```
+**Recommended: Nix build** (automatically handles all dependencies)
 
-**RHEL/CentOS/Fedora Systems**
 ```bash
-# 1. Install Rust toolchain (if not already installed)
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-source ~/.cargo/env
-
-# 2. Install build dependencies
-# For RHEL/CentOS 8+
-sudo dnf groupinstall "Development Tools"
-sudo dnf install pkg-config openssl-devel git
-
-# For older RHEL/CentOS 7
-# sudo yum groupinstall "Development Tools"
-# sudo yum install pkg-config openssl-devel git
-
-# 3. Install runtime dependencies
-sudo dnf install numactl ipmitool ethtool util-linux pciutils
-# For CentOS 7: sudo yum install numactl ipmitool ethtool util-linux pciutils
+# Install Nix (if not already installed)
+curl -L https://install.determinate.systems/nix | sh -s -- install
+. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
 
-# 4. Clone and build
+# Clone, build, and run
 git clone https://github.com/sfcompute/hardware_report.git
 cd hardware_report
-cargo build --release
-
-# 5. Run the tool
-sudo ./target/release/hardware_report
-```
-
-**One-Liner for Ubuntu/Debian (Traditional Build)**
-```bash
-# Complete setup and build without Nix:
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && \
-source ~/.cargo/env && \
-sudo apt-get update && \
-sudo apt-get install -y build-essential pkg-config libssl-dev git numactl ipmitool ethtool util-linux pciutils && \
-git clone https://github.com/sfcompute/hardware_report.git && \
-cd hardware_report && \
-cargo build --release && \
-echo "Build complete! Run with: sudo ./target/release/hardware_report" && \
-sudo ./target/release/hardware_report
-```
-
-### Option 3: Pre-built Releases (Recommended for Quick Setup)
-
-Instead of building from source, you can download pre-built binaries and Debian packages from our [GitHub Releases](https://github.com/sfcompute/hardware_report/releases) page.
-
-**Available Release Artifacts:**
-- `hardware_report-linux-x86_64-{version}.tar.gz` - Pre-compiled Linux binary
-- `hardware-report_{version}_amd64.deb` - Debian package with automatic dependency management
-- SHA256 checksums for all artifacts
-
-**Option 3a: Pre-built Binary**
-```bash
-# Download the latest release
-curl -s https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
-  | grep "browser_download_url.*tar.gz" \
-  | cut -d '"' -f 4 \
-  | wget -i -
-
-# Download and verify checksum
-curl -s https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
-  | grep "browser_download_url.*tar.gz.sha256" \
-  | cut -d '"' -f 4 \
-  | wget -i -
-
-sha256sum -c hardware_report-linux-x86_64-*.tar.gz.sha256
-
-# Install runtime dependencies
-sudo apt-get update && sudo apt-get install -y numactl ipmitool ethtool util-linux pciutils
-
-# Extract and run
-tar xzf hardware_report-linux-x86_64-*.tar.gz
-chmod +x hardware_report-linux-x86_64
-sudo ./hardware_report-linux-x86_64
-```
-
-**Option 3b: Debian Package (Ubuntu/Debian)**
-```bash
-# Download the latest Debian package
-curl -s https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
-  | grep "browser_download_url.*\.deb" \
-  | cut -d '"' -f 4 \
-  | wget -i -
-
-# Install with automatic dependency resolution
-sudo apt update
-sudo apt install -y ./hardware-report_*_amd64.deb
-
-# Run the tool
-sudo hardware_report
-```
-
-### Advanced Build Methods
-
-**For Teams with Existing Nix Infrastructure**
-```bash
-git clone https://github.com/sfcompute/hardware_report.git && \
-cd hardware_report && \
-nix build && \
+nix build
 sudo ./result/bin/hardware_report
 ```
 
-**Development Environment Setup (Nix)**
-```bash
-# Enter development shell with all dependencies
-nix develop
-
-# Build with cargo
-cargo build --release
-
-# Execute binary
-sudo ./target/release/hardware_report
-```
-
-**Development with direnv Integration**
-```bash
-# Automatic environment loading
-direnv allow
-cargo build --release
-```
-
----
-
-## Build Systems & CI/CD
-
-### Build System Comparison
+Output: `<chassis_serial>_hardware_report.toml`
 
-| Method | Pros | Cons | Best For |
-|--------|------|------|----------|
-| **Nix** | Self-contained, reproducible, automatic dependencies | Learning curve, additional tool | Production, reproducible builds |
-| **Cargo** | Native Rust, familiar to developers, fast | Manual dependency management | Development, existing Rust workflows |
-| **Docker** | Cross-platform, isolated builds | Requires Docker setup | CI/CD, cross-compilation |
-| **Pre-built** | No build required, instant setup | Less flexibility, trust requirements | Quick evaluation, production deployment |
+**Pre-built .deb package:** Download from [GitHub Releases](https://github.com/sfcompute/hardware_report/releases)
 
-### Nix Build System (Recommended for Production)
-The project leverages Nix for reproducible builds that automatically handle all dependencies:
+**Other installation methods:** See [docs/INSTALLATION.md](docs/INSTALLATION.md)
 
-**Benefits of Nix Build:**
-- **Dependency Management**: Automatically includes `numactl`, `ipmitool`, `ethtool`, `lscpu`, `lspci`
-- **Reproducibility**: Consistent builds across different environments
-- **Self-Contained**: No system dependency installation required
-- **Cross-Platform**: Supports Linux and macOS targets
+## Documentation
 
-### Traditional Cargo Build System
-For teams preferring standard Rust tooling:
+| Document | Description |
+|----------|-------------|
+| [docs/INSTALLATION.md](docs/INSTALLATION.md) | All installation methods (Nix, Cargo, pre-built releases) |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Hexagonal architecture overview |
+| [docs/API.md](docs/API.md) | Library API reference |
+| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment guide |
 
-**System Prerequisites by Distribution:**
+## Contributing
 
-**Ubuntu/Debian:**
 ```bash
-sudo apt-get update && sudo apt-get install -y \
-  build-essential \
-  pkg-config \
-  libssl-dev \
-  numactl \
-  ipmitool \
-  ethtool \
-  util-linux \
-  pciutils
-```
-
-**RHEL/CentOS/Fedora:**
-```bash
-# Build dependencies
-sudo dnf groupinstall "Development Tools"
-sudo dnf install pkg-config openssl-devel
-
-# Runtime dependencies
-sudo dnf install numactl ipmitool ethtool util-linux pciutils
-```
-
-**Alpine Linux:**
-```bash
-# Build dependencies
-apk add --no-cache \
-  build-base \
-  pkgconfig \
-  openssl-dev \
-  git
-
-# Runtime dependencies
-apk add --no-cache \
-  numactl \
-  ipmitool \
-  ethtool \
-  util-linux \
-  pciutils
-```
-
-### Cross-Platform Builds with Docker
-```bash
-# Ensure Docker is running
-docker ps
-
-# Build Linux binary
-make linux
-
-# Build for all supported platforms
-make all
-```
-
-### Static Binary Builds
-For maximum portability, create static binaries:
-
-```bash
-# Install musl target for static linking
-rustup target add x86_64-unknown-linux-musl
-
-# Build static binary
-cargo build --target x86_64-unknown-linux-musl --release
-
-# The static binary requires no runtime dependencies except system tools
-```
-
-### Automated Release Pipeline
-The project includes GitHub Actions workflows for:
-- Automated testing on pull requests
-- Code formatting and linting validation
-- Release builds triggered by version tags
-- Binary artifact generation with SHA256 checksums
-
----
-
-## Sample Output
-
-### Console Summary
-```bash
-System Summary:
-==============
-CPU: AMD EPYC 7763 (2 Sockets, 64 Cores/Socket, 2 Threads/Core, 8 NUMA Nodes)
-Total: 128 Cores, 256 Threads
-Memory: 512GB DDR4 @ 3200 MHz
-Storage: 15.36 TB (Total: 15.37 TB)
-Storage Devices: 3.84TB + 3.84TB + 3.84TB + 3.84TB
-BIOS: AMI 2.4.3 (01/15/2024)
-Chassis: SuperMicro SC847BE2C-R1K28LPB (S/N: S454857X9822867)
-Motherboard: Supermicro X13DEG-OAD v1.01 (S/N: OM237S046931)
-
-Network Interfaces:
-  enp1s0 - Intel Corporation E810-XXVDA4 (E4:43:4B:43:07:24) [Speed: 100000baseT/Full] [NUMA: 0]
-  enp2s0 - Intel Corporation E810-XXVDA4 (E4:43:4B:43:07:25) [Speed: 100000baseT/Full] [NUMA: 0]
-
-GPUs:
-  NVIDIA H100 PCIe - NVIDIA (86:00.0) [NUMA: 0]
-  NVIDIA H100 PCIe - NVIDIA (87:00.0) [NUMA: 1]
-
-NUMA Topology:
-  Node 0:
-    Memory: 128G
-    CPUs: 0-15,128-143
-    Devices:
-      GPU - NVIDIA H100 PCIe (PCI ID: 86:00.0)
-      NIC - Intel E810-XXVDA4 (PCI ID: A1:00.0)
-
-  Node 1:
-    Memory: 128G
-    CPUs: 16-31,144-159
-    Devices:
-      GPU - NVIDIA H100 PCIe (PCI ID: 87:00.0)
-
-Filesystems:
-  /dev/nvme0n1p2 (xfs) - 3.8T total, 2.1T used, 1.7T available, mounted on /
-  /dev/nvme1n1 (xfs) - 3.8T total, 1.9T used, 1.9T available, mounted on /data
-```
-
-### Structured TOML Report (Sample Sections)
-
-```toml
-hostname = "gpu120B"
-bmc_ip = "10.49.136.120"
-bmc_mac = "7c:c2:55:50:ca:55"
-
-[summary]
-total_memory = "1.0Ti"
-memory_config = "DDR5 @ 4800 MT/s"
-total_storage = "2.6 TB"
-total_storage_tb = 2.6200195312494543
-total_gpus = 8
-total_nics = 15
-cpu_summary = "Intel(R) Xeon(R) Platinum 8462Y+ (2 Sockets, 32 Cores/Socket, 2 Threads/Core, 2 NUMA Nodes)"
-
-[summary.bios]
-vendor = "American Megatrends International, LLC."
-version = "2.1.V1"
-release_date = "03/20/2024"
-firmware_version = "N/A"
-
-[summary.chassis]
-manufacturer = "Supermicro"
-type_ = "Other"
-serial = "C8010MM29A40285"
-
-[summary.motherboard]
-manufacturer = "Supermicro"
-product_name = "X13DEG-OAD"
-version = "1.01"
-serial = "OM234S043296"
-
-[summary.cpu_topology]
-total_cores = 64
-total_threads = 128
-sockets = 2
-cores_per_socket = 32
-threads_per_core = 2
-numa_nodes = 2
-cpu_model = "Intel(R) Xeon(R) Platinum 8462Y+"
-
-[hardware.cpu]
-model = "Intel(R) Xeon(R) Platinum 8462Y+"
-cores = 32
-threads = 2
-sockets = 2
-speed = " MHz"
-
-[hardware.memory]
-total = "1.0Ti"
-type_ = "DDR5"
-speed = "4800 MT/s"
-
-[[hardware.memory.modules]]
-size = "32 GB"
-type_ = "DDR5"
-speed = "4800 MT/s"
-location = "P1-DIMMA1"
-
-[[hardware.memory.modules]]
-size = "32 GB"
-type_ = "DDR5"
-speed = "4800 MT/s"
-location = "P1-DIMMA2"
-
-[[hardware.storage.devices]]
-name = "nvme0n1"
-type_ = "disk"
-size = "894.3G"
-model = "Micron_7450_MTFDKBA960TFR"
-
-[[hardware.storage.devices]]
-name = "nvme1n1"
-type_ = "disk"
-size = "894.3G"
-model = "Micron_7450_MTFDKBA960TFR"
-
-[[hardware.gpus.devices]]
-index = 0
-name = "NVIDIA H100 80GB HBM3"
-uuid = "GPU-9856b125-7617-39e4-f265-a21213c1d988"
-memory = "81559 MiB"
-pci_id = "10de:2330"
-vendor = "NVIDIA Corporation"
-
-[[hardware.gpus.devices]]
-index = 1
-name = "NVIDIA H100 80GB HBM3"
-uuid = "GPU-84a1aceb-6bec-9067-95a8-32bf31bb9b2c"
-memory = "81559 MiB"
-pci_id = "10de:2330"
-vendor = "NVIDIA Corporation"
-
-[[network.interfaces]]
-name = "enp217s0f0np0"
-mac = "a0:88:c2:09:7c:c8"
-ip = "10.49.11.120"
-speed = "100000Mb/s"
-type_ = "ether"
-vendor = "Mellanox Technologies"
-model = "MT2892 Family [ConnectX-6 Dx]"
-pci_id = "15b3:101d"
-
-[[network.interfaces]]
-name = "ibp26s0"
-mac = "00:00:10:49:fe:80:00:00:00:00:00:00:a0:88:c2:03:00:4b:64:18"
-ip = ""
-speed = "400000Mb/s"
-type_ = "infiniband"
-vendor = "Mellanox Technologies"
-model = "MT2910 Family [ConnectX-7]"
-pci_id = "15b3:1021"
-```
-
----
-
-## Architecture & Dependencies
-
-### System Requirements
-- **Operating System**: Linux (primary target), macOS (compatibility mode)
-- **Privileges**: Root access recommended for complete hardware introspection
-- **Architecture**: x86_64 (primary), ARM64 (Apple Silicon), with cross-compilation support
-
-### Runtime Dependencies
-
-**Linux (Nix-built binaries include all dependencies automatically):**
-- `numactl` - NUMA topology information
-- `ipmitool` - BMC information extraction
-- `ethtool` - Network interface details
-- `lscpu` - CPU configuration data
-- `lspci` - PCI device enumeration
-- `dmidecode` - System/BIOS/memory information
-
-**macOS (Built-in tools, no additional dependencies required):**
-- `system_profiler` - Hardware configuration data
-- `sysctl` - System configuration information
-- `ioreg` - Hardware registry information
-
-**Note**: 
-- NVIDIA drivers must be installed separately for GPU detection on Linux
-- Some Linux-specific features (NUMA topology, IPMI/BMC) are not available on macOS
-
-### Core Libraries
-- **regex** - System command output parsing
-- **serde** - Data serialization framework
-- **toml** - TOML format generation
-
----
-
-## Deployment Considerations
-
-### Production Deployment Options
-
-**Option 1: Pre-built Debian Package (Recommended for Production)**
-```bash
-# Download latest Debian package from GitHub Releases
-curl -s https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
-  | grep "browser_download_url.*\.deb" \
-  | cut -d '"' -f 4 \
-  | wget -i -
-
-# Install with automatic dependency resolution
-sudo apt update && sudo apt install -y ./hardware-report_*_amd64.deb
-
-# Deploy across multiple servers
-ansible servers -m copy -a "src=hardware-report_*_amd64.deb dest=/tmp/"
-ansible servers -m apt -a "deb=/tmp/hardware-report_*_amd64.deb state=present"
-```
-
-**Option 2: Pre-built Binary Deployment**
-```bash
-# Download and verify pre-built binary
-curl -s https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
-  | grep "browser_download_url.*tar.gz" \
-  | cut -d '"' -f 4 \
-  | wget -i -
-
-# Extract and deploy to target systems
-tar xzf hardware_report-linux-x86_64-*.tar.gz
-scp hardware_report-linux-x86_64 user@target:/usr/local/bin/hardware_report
-
-# Ensure runtime dependencies are installed on all target systems
-ansible all -m package -a "name=numactl,ipmitool,ethtool,util-linux,pciutils state=present"
-```
-
-**Option 3: Build-from-Source Deployment**
-```bash
-# For environments that require building from source
-# Using Nix-built package (includes all dependencies)
-nix build .#deb
-sudo apt install -y ./result/hardware-report_*_amd64.deb
-
-# Or using traditional cargo build
-cargo build --release
-sudo cp target/release/hardware_report /usr/local/bin/
-```
-
-### Automation Integration
-1. **Scheduled Execution**: Use cron or systemd timers for regular inventory updates
-2. **Configuration Management**: Deploy via Ansible, Puppet, or Chef
-3. **Report Collection**: Centralize TOML files using rsync, SFTP, or object storage
-4. **Version Control**: Track infrastructure changes through Git
-
-### Dependency Management Strategies
-
-**Nix Approach** (Zero manual dependency management):
-- All dependencies bundled automatically
-- Consistent across all environments
-- No version conflicts or missing tools
-
-**Traditional Approach** (Manual dependency management):
-- Explicit control over system packages
-- Integration with existing package management
-- Requires dependency installation on each target system
-
-**Container Approach** (Isolated execution):
-```dockerfile
-FROM ubuntu:22.04
-RUN apt-get update && apt-get install -y \
-    numactl ipmitool ethtool util-linux pciutils
-COPY hardware_report /usr/local/bin/
-CMD ["hardware_report"]
+nix develop
+cargo test && cargo clippy && cargo fmt
 ```
 
-### Error Handling
-The tool gracefully handles common failure scenarios:
-- Missing system utilities
-- Insufficient privileges
-- Unavailable hardware components
-- Command output parsing errors
-- Network interface collection failures
+## License
 
-### Troubleshooting
-**Debian Package Issues**
-```bash
-# Remove broken installation
-sudo apt remove -y hardware-report
-
-# Rebuild and reinstall
-git pull
-rm -rf result
-nix build .#deb --rebuild
-sudo apt install -y ./result/hardware-report_0.1.7_amd64.deb
-```
+[MIT](LICENSE)
 
 ---
 
-## Project Information
-
-**Repository**: https://github.com/sfcompute/hardware_report  
-**Author**: Kenny Sheridan, Supercomputing Engineer  
-**License**: Open Source  
-**Target Community**: Open-source GPU infrastructure community
-
-### Contributing
-Pull requests welcome. For major changes, please open an issue first to discuss proposed modifications.
-
-### Support
-For issues and feature requests, please use the GitHub issue tracker.
+**Built for infrastructure management at scale** | [Issues](https://github.com/sfcompute/hardware_report/issues) | [Releases](https://github.com/sfcompute/hardware_report/releases)
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..7ce0f61
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,147 @@
+# API Reference
+
+Hardware Report can be used as a library in your Rust projects.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Types](#core-types)
+- [Service Creation](#service-creation)
+- [Examples](#examples)
+
+## Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+hardware_report = { git = "https://github.com/sfcompute/hardware_report.git" }
+```
+
+## Quick Start
+
+```rust
+use hardware_report::create_service;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let service = create_service()?;
+    let report = service.collect_hardware_info().await?;
+    
+    println!("CPU: {}", report.hardware.cpu.model);
+    println!("Memory: {}", report.hardware.memory.total);
+    println!("GPUs: {}", report.hardware.gpus.devices.len());
+    
+    Ok(())
+}
+```
+
+## Core Types
+
+### HardwareReport
+
+The main report structure containing all collected hardware information.
+
+```rust
+pub struct HardwareReport {
+    pub hostname: String,
+    pub hardware: HardwareInfo,
+    pub network: NetworkInfo,
+    pub summary: Summary,
+}
+```
+
+### CpuInfo
+
+```rust
+pub struct CpuInfo {
+    pub model: String,
+    pub cores: u32,
+    pub threads: u32,
+    pub sockets: u32,
+    pub speed: String,
+    pub vendor: String,
+    pub architecture: String,
+    pub frequency_mhz: u32,
+    pub cache_l1d_kb: Option<u32>,
+    pub cache_l2_kb: Option<u32>,
+    pub cache_l3_kb: Option<u32>,
+}
+```
+
+### MemoryInfo
+
+```rust
+pub struct MemoryInfo {
+    pub total: String,
+    pub type_: String,
+    pub speed: String,
+    pub modules: Vec<MemoryModule>,
+}
+```
+
+### StorageDevice
+
+```rust
+pub struct StorageDevice {
+    pub name: String,
+    pub device_type: StorageType,  // Nvme, Ssd, Hdd
+    pub size: String,
+    pub size_bytes: u64,
+    pub model: String,
+    pub serial_number: Option<String>,
+}
+```
+
+### GpuDevice
+
+```rust
+pub struct GpuDevice {
+    pub index: u32,
+    pub name: String,
+    pub uuid: String,
+    pub memory: String,
+    pub memory_total_mb: u32,
+    pub vendor: String,
+    pub pci_id: String,
+}
+```
+
+### NetworkInterface
+
+```rust
+pub struct NetworkInterface {
+    pub name: String,
+    pub mac: String,
+    pub ip: String,
+    pub speed: String,
+    pub mtu: Option<u32>,
+    pub link_state: Option<String>,
+}
+```
+
+## Service Creation
+
+```rust
+use hardware_report::{create_service, create_service_with_config};
+
+// Default configuration
+let service = create_service()?;
+
+// Custom configuration
+let config = ServiceConfig {
+    timeout_seconds: 30,
+    collect_gpu: true,
+    collect_network: true,
+};
+let service = create_service_with_config(config)?;
+```
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+
+- `examples/basic_usage.rs` - Simple hardware collection
+- `examples/library_usage.rs` - Library integration patterns
+- `examples/custom_analysis.rs` - Custom data processing
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..eb73c31
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,90 @@
+# Architecture Overview
+
+Hardware Report is built with **hexagonal (ports & adapters) architecture** for clean separation of concerns.
+
+## Table of Contents
+
+- [Design Principles](#design-principles)
+- [Layer Structure](#layer-structure)
+- [Component Diagram](#component-diagram)
+- [Key Benefits](#key-benefits)
+
+## Design Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Domain Independence** | Domain layer has no knowledge of adapters or I/O |
+| **Pure Parsers** | Parsing functions take strings, return Results - no side effects |
+| **Trait Abstraction** | All platform-specific code behind trait interfaces |
+| **Multi-Method Detection** | Each adapter tries multiple methods, returns best result |
+| **Graceful Degradation** | Partial data is better than no data - always return something |
+
+## Layer Structure
+
+```
+src/
+├── domain/           # Core business logic (platform-agnostic)
+│   ├── entities.rs   # Data structures (CpuInfo, MemoryInfo, etc.)
+│   ├── errors.rs     # Domain errors
+│   ├── parsers/      # Pure parsing functions (no I/O)
+│   │   ├── cpu.rs
+│   │   ├── memory.rs
+│   │   ├── storage.rs
+│   │   ├── network.rs
+│   │   └── gpu.rs
+│   └── services/     # Domain services (orchestration)
+│
+├── ports/            # Interface definitions
+│   ├── primary/      # Offered interfaces (what we provide)
+│   │   └── reporting.rs
+│   └── secondary/    # Required interfaces (what we need)
+│       ├── system.rs
+│       ├── command.rs
+│       └── publisher.rs
+│
+└── adapters/         # Implementations
+    ├── primary/      # CLI, library entry points
+    └── secondary/    # Platform-specific implementations
+        ├── system/
+        │   ├── linux.rs
+        │   └── macos.rs
+        ├── command/
+        │   └── unix.rs
+        └── publisher/
+            ├── file.rs
+            └── http.rs
+```
+
+## Component Diagram
+
+```
+                    ┌──────────────────────────────────────┐
+                    │         Core Domain (Pure)           │
+                    │                                      │
+  Primary Ports     │  ┌────────────────────────────┐     │    Secondary Ports
+  (Inbound)         │  │    Domain Services         │     │    (Outbound)
+                    │  │  • HardwareCollectionSvc   │     │
+ ┌─────────────┐    │  │  • ReportGenerationSvc     │     │    ┌──────────────────┐
+ │   CLI       │───►│  └────────────────────────────┘     │───►│ System Adapters  │
+ │             │    │                                      │    │ • LinuxProvider  │
+ │ hardware_   │    │  ┌────────────────────────────┐     │    │ • MacOSProvider  │
+ │ report      │    │  │    Domain Entities         │     │    └──────────────────┘
+ └─────────────┘    │  │  • CpuInfo, MemoryInfo     │     │
+                    │  │  • StorageInfo, GpuInfo    │     │    ┌──────────────────┐
+ ┌─────────────┐    │  │  • NetworkInfo, SystemInfo │     │───►│ Command Executor │
+ │  Library    │───►│  └────────────────────────────┘     │    │ • UnixExecutor   │
+ │             │    │                                      │    └──────────────────┘
+ │ create_     │    │  ┌────────────────────────────┐     │
+ │ service()   │    │  │    Pure Parsers            │     │    ┌──────────────────┐
+ └─────────────┘    │  │  • CPU, Memory, Storage    │     │───►│ Publishers       │
+                    │  │  • GPU, Network, System    │     │    │ • FilePublisher  │
+                    │  └────────────────────────────┘     │    │ • HttpPublisher  │
+                    └──────────────────────────────────────┘    └──────────────────┘
+```
+
+## Key Benefits
+
+- **Testable** - Mock any external dependency for thorough testing
+- **Flexible** - Swap system providers or publishers independently
+- **Maintainable** - Clear boundaries between business logic and infrastructure
+- **Platform Independent** - Core domain stays pure, adapters handle OS specifics
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 0000000..5ed235a
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,123 @@
+# Deployment Guide
+
+## Table of Contents
+
+- [Production Deployment](#production-deployment)
+- [Automation Integration](#automation-integration)
+- [Troubleshooting](#troubleshooting)
+
+## Production Deployment
+
+### Debian Package (Recommended)
+
+```bash
+# Download and install
+curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
+  | grep "browser_download_url.*\.deb" | cut -d '"' -f 4 | wget -qi -
+sudo apt install -y ./hardware-report_*_amd64.deb
+
+# Run
+sudo hardware_report
+```
+
+### Multi-Server Deployment with Ansible
+
+```bash
+# Deploy package to all servers
+ansible servers -m copy -a "src=hardware-report_*_amd64.deb dest=/tmp/"
+ansible servers -m apt -a "deb=/tmp/hardware-report_*_amd64.deb state=present"
+
+# Run on all servers
+ansible servers -m shell -a "sudo hardware_report" --become
+```
+
+### Binary Deployment
+
+```bash
+# Download binary
+curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
+  | grep "browser_download_url.*tar.gz" | cut -d '"' -f 4 | wget -qi -
+tar xzf hardware_report-linux-x86_64-*.tar.gz
+
+# Deploy to target
+scp hardware_report-linux-x86_64 user@target:/usr/local/bin/hardware_report
+
+# Ensure runtime dependencies on target
+ssh user@target "sudo apt-get install -y numactl ipmitool ethtool pciutils"
+```
+
+## Automation Integration
+
+### Scheduled Execution (systemd timer)
+
+```ini
+# /etc/systemd/system/hardware-report.service
+[Unit]
+Description=Hardware Report Collection
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/hardware_report
+WorkingDirectory=/var/lib/hardware-report
+
+# /etc/systemd/system/hardware-report.timer
+[Unit]
+Description=Run Hardware Report daily
+
+[Timer]
+OnCalendar=daily
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+```bash
+sudo systemctl enable --now hardware-report.timer
+```
+
+### Cron
+
+```bash
+# Daily at 2 AM
+echo "0 2 * * * root /usr/bin/hardware_report" | sudo tee /etc/cron.d/hardware-report
+```
+
+## Troubleshooting
+
+### Permission Issues
+
+```bash
+# Most hardware detection requires root
+sudo hardware_report
+
+# Or add user to required groups
+sudo usermod -aG disk,video $USER
+```
+
+### Missing Dependencies
+
+```bash
+# Check which tools are available
+which numactl ipmitool ethtool lspci dmidecode nvidia-smi
+
+# Install missing (Ubuntu/Debian)
+sudo apt-get install -y numactl ipmitool ethtool pciutils dmidecode
+```
+
+### Incomplete GPU Detection
+
+```bash
+# Verify NVIDIA driver is loaded
+nvidia-smi
+
+# If not working, install drivers
+sudo apt-get install -y nvidia-driver-535  # or appropriate version
+```
+
+### Debug Output
+
+```bash
+# Enable verbose logging
+RUST_LOG=debug sudo hardware_report
+```
diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md
new file mode 100644
index 0000000..4454055
--- /dev/null
+++ b/docs/INSTALLATION.md
@@ -0,0 +1,98 @@
+# Installation Guide
+
+## Table of Contents
+
+- [Nix Build (Recommended)](#nix-build-recommended)
+- [Pre-built Releases](#pre-built-releases)
+- [Cargo Install](#cargo-install)
+- [Traditional Cargo Build](#traditional-cargo-build)
+- [Runtime Dependencies](#runtime-dependencies)
+
+## Nix Build (Recommended)
+
+Nix automatically handles all build and runtime dependencies.
+
+```bash
+# Install Nix (if not already installed)
+curl -L https://install.determinate.systems/nix | sh -s -- install
+. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+
+# Clone, build, and run
+git clone https://github.com/sfcompute/hardware_report.git
+cd hardware_report
+nix build
+sudo ./result/bin/hardware_report
+```
+
+**Development shell:**
+```bash
+nix develop
+cargo build --release
+```
+
+## Pre-built Releases
+
+Download from [GitHub Releases](https://github.com/sfcompute/hardware_report/releases):
+
+**Debian/Ubuntu package:**
+```bash
+curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
+  | grep "browser_download_url.*\.deb" | cut -d '"' -f 4 | wget -qi -
+sudo apt install -y ./hardware-report_*_amd64.deb
+sudo hardware_report
+```
+
+**Standalone binary:**
+```bash
+curl -sL https://api.github.com/repos/sfcompute/hardware_report/releases/latest \
+  | grep "browser_download_url.*tar.gz" | cut -d '"' -f 4 | wget -qi -
+tar xzf hardware_report-linux-x86_64-*.tar.gz
+sudo ./hardware_report-linux-x86_64
+```
+
+## Cargo Install
+
+```bash
+git clone https://github.com/sfcompute/hardware_report.git
+cd hardware_report
+cargo install --path .
+sudo hardware_report
+```
+
+## Traditional Cargo Build
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get update && sudo apt-get install -y \
+  build-essential pkg-config libssl-dev git \
+  numactl ipmitool ethtool util-linux pciutils
+
+git clone https://github.com/sfcompute/hardware_report.git
+cd hardware_report
+cargo build --release
+sudo ./target/release/hardware_report
+```
+
+**RHEL/Fedora:**
+```bash
+sudo dnf groupinstall "Development Tools"
+sudo dnf install pkg-config openssl-devel numactl ipmitool ethtool util-linux pciutils
+
+git clone https://github.com/sfcompute/hardware_report.git
+cd hardware_report
+cargo build --release
+sudo ./target/release/hardware_report
+```
+
+## Runtime Dependencies
+
+| Tool | Purpose |
+|------|---------|
+| `numactl` | NUMA topology |
+| `ipmitool` | BMC/IPMI data |
+| `ethtool` | Network interface details |
+| `lspci` | PCI device enumeration |
+| `dmidecode` | System/BIOS/memory info |
+| `nvidia-smi` | GPU detection (optional) |
+
+> **Note:** Nix builds bundle all dependencies automatically.