From b4a9623195573db7aef463ba23484c21a9f8153c Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Wed, 17 Dec 2025 14:12:54 +0000
Subject: [PATCH] docs: add comprehensive getting started guide to README

Added a detailed Getting Started section to the main README covering:
- Installation instructions
- Basic usage for all CLI commands (decode, strip, cfg, obfuscate, analyze)
- Comprehensive TUI usage guide with both methods (--tui flag and --emit-debug + azoth tui)
- Overview of available CLI commands with examples
- Link to detailed CLI documentation

The guide provides clear examples and explanations for users to quickly
understand how to use Azoth's core functionality.

Co-authored-by: Nima Rasooli <EmperorOrokuSaki@users.noreply.github.com>
---
 README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a52f527..8b51824 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,103 @@ Azoth is under active development: the parsing pipeline, CFG builder, and severa
 
 ## Getting Started
 
-Azoth is available through a command-line interface. This could be used for local development, testing, and experimentation with bytecode obfuscation.
+Azoth is available through a command-line interface for local development, testing, and experimentation with bytecode obfuscation.
+
+### Installation
+
+Build the CLI from source:
+
+```bash
+cargo build --release --bin azoth
+```
+
+The binary will be available at `target/release/azoth`.
+
+### Basic Usage
+
+Azoth provides several commands for working with EVM bytecode. Input can be provided as a hex string (with or without `0x` prefix) or as a path to a file containing bytecode.
+
+#### Decode Bytecode
+
+Convert bytecode to human-readable assembly instructions:
+
+```bash
+azoth decode 0x608060405234801561001057600080fd5b50
+azoth decode path/to/bytecode.hex
+```
+
+#### Strip Init Code and Auxdata
+
+Extract runtime bytecode by removing initialization code and auxiliary data:
+
+```bash
+azoth strip 0x608060405234801561001057600080fd5b50
+azoth strip --raw path/to/bytecode.hex
+```
+
+#### Generate Control Flow Graph
+
+Create a Graphviz visualization of the bytecode control flow:
+
+```bash
+azoth cfg 0x608060405234801561001057600080fd5b50
+azoth cfg --output graph.dot path/to/bytecode.hex
+```
+
+#### Obfuscate Bytecode
+
+Apply obfuscation transforms to make bytecode harder to analyze:
+
+```bash
+azoth obfuscate --input path/to/deployment.hex --runtime path/to/runtime.hex
+azoth obfuscate --input deploy.hex --runtime runtime.hex --seed 12345
+azoth obfuscate --input deploy.hex --runtime runtime.hex --passes shuffle,jump_transform
+```
+
+Available transforms: `shuffle`, `jump_transform`, `opaque_pred`, `arithmetic_chain`, `push_split`, `storage_gates`, `slot_shuffle`, `cluster_shuffle`, `splice`. The `function_dispatcher` transform is always applied automatically when detected.
+
+#### Analyze Obfuscation Quality
+
+Generate multiple obfuscated variants and measure preservation of original bytecode:
+
+```bash
+azoth analyze 50 path/to/runtime.hex
+azoth analyze 25 0x608060405234801561001057600080fd5b50 --output report.md
+```
+
+### Using the TUI (Terminal User Interface)
+
+Azoth includes an interactive TUI for exploring obfuscation debug traces. The TUI provides a visual representation of how transforms modified the bytecode control flow graph.
+
+There are two ways to launch the TUI:
+
+#### Option 1: Direct Launch with `--tui`
+
+Add the `--tui` flag to the obfuscate command to automatically launch the TUI after obfuscation completes:
+
+```bash
+azoth obfuscate --input deploy.hex --runtime runtime.hex --tui
+```
+
+#### Option 2: Save Debug File and Launch Separately
+
+First, obfuscate bytecode and save the debug trace to a file:
+
+```bash
+azoth obfuscate --input deploy.hex --runtime runtime.hex --emit-debug debug.json
+```
+
+Then launch the TUI to explore the debug file:
+
+```bash
+azoth tui debug.json
+```
+
+This two-step approach is useful when you want to save debug traces for later analysis or share them with others.
+
+### Additional Resources
+
+For detailed information about CLI commands, options, and advanced usage patterns, see the [CLI documentation](crates/cli/README.md).
 
 ## Contributing