diff --git a/fusion/src/about_cli.md b/fusion/src/about_cli.md
index 8fd3cee6..9ef43b68 100644
--- a/fusion/src/about_cli.md
+++ b/fusion/src/about_cli.md
@@ -4,12 +4,16 @@
 <!-- MarkdownJ can't handle backticks in headers -->
 # About the <code>fusion</code> CLI
 
-The `fusion` command-line interface is intended to support evaluation of Fusion code across a 
-variety of use cases.  It provides a number of commands that can be composed in a sequence of 
-steps within a single execution of the CLI.
+The `fusion` command-line interface is a powerful tool for evaluating Fusion code across a variety of use cases. It provides multiple commands that can be composed in sequences to build complex data processing workflows.
 
-> ⚠️ This document is a work in progress! We'd love to hear your feedback in 
-> [this Discussion thread](https://github.com/orgs/ion-fusion/discussions/213).
+> **📚 Looking for comprehensive CLI documentation?**
+> 
+> * **[CLI Quick Start](cli_quickstart.html)** - Get started in minutes
+> * **[CLI Tutorial](tutorial_cli.html)** - Step-by-step learning guide  
+> * **[CLI Reference](cli_reference.html)** - Complete command documentation
+> * **[CLI Troubleshooting](cli_troubleshooting.html)** - Common issues and solutions
+
+This document provides an overview of CLI concepts and design principles.
 
 The `fusion` executable requires at least one argument: a command to perform.
 
diff --git a/fusion/src/cli_quickstart.md b/fusion/src/cli_quickstart.md
new file mode 100644
index 00000000..50d2cbc0
--- /dev/null
+++ b/fusion/src/cli_quickstart.md
@@ -0,0 +1,222 @@
+<!-- Copyright Ion Fusion contributors. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Ion Fusion CLI Quick Start
+
+Get up and running with the Ion Fusion CLI in minutes. This guide covers installation, basic usage, and your first Fusion programs.
+
+## Installation
+
+### Option 1: Build from Source (Recommended)
+
+**Prerequisites:**
+- Java 8 or later ([Corretto](https://aws.amazon.com/corretto/) recommended)
+- Git
+
+**Steps:**
+```bash
+# Clone the repository
+git clone https://github.com/ion-fusion/fusion-java.git
+cd fusion-java
+
+# Build the CLI
+./gradlew release
+
+# Add to PATH
+export PATH=$PATH:$PWD/build/install/fusion/bin
+
+# Verify installation
+fusion version
+```
+
+### Option 2: Download Pre-built Binary *(Coming Soon)*
+
+Pre-built binaries will be available from the [releases page](https://github.com/ion-fusion/fusion-java/releases) once version 1.0 is released.
+
+## First Steps
+
+### 1. Verify Installation
+
+```bash
+fusion help
+```
+
+You should see a list of available commands.
+
+### 2. Your First Expression
+
+```bash
+fusion eval '(+ 1 2 3)'
+```
+**Output:** `6`
+
+### 3. Working with Data
+
+```bash
+# Create a simple data structure
+fusion eval '{ name: "Alice", age: 30, hobbies: ["reading", "coding"] }'
+```
+
+**Output:** `{name:"Alice",age:30,hobbies:["reading","coding"]}`
+
+### 4. Interactive Mode
+
+```bash
+fusion repl
+```
+
+Try these expressions in the REPL:
+```fusion
+$ (define greeting "Hello, Fusion!")
+$ greeting
+"Hello, Fusion!"
+$ (define (square x) (* x x))
+$ (square 5)
+25
+$ (exit)
+```
+
+## Essential Commands
+
+### `eval` - Quick Expressions
+Perfect for one-liners and testing:
+```bash
+fusion eval '(* 7 6)'                    # Math: 42
+fusion eval '(string_length "hello")'    # Needs string module
+```
+
+### `load` - Run Scripts
+Create a file `hello.fusion`:
+```fusion
+(define (greet name)
+  (string_append "Hello, " name "!"))
+
+(greet "World")
+```
+
+Run it:
+```bash
+fusion load hello.fusion
+```
+
+### `require` - Import Modules
+```bash
+# Import string functions, then use them
+fusion require '/fusion/string' ';' eval '(string_length "test")'
+```
+
+### `repl` - Interactive Development
+```bash
+fusion repl
+```
+
+## Common Patterns
+
+### Data Processing
+```bash
+# Process Ion data
+echo '{"count": 5}' | fusion eval '(define data (read)) (+ (. data "count") 10)'
+```
+
+### Module Usage
+```bash
+# Use list processing functions
+fusion require '/fusion/list' ';' eval '(map (lambda (x) (* x 2)) [1 2 3 4])'
+```
+
+### Script Development
+Create `process.fusion`:
+```fusion
+// Read input, process it, write output
+(define input (read))
+(define result (* input 2))
+(writeln "Double of " input " is " result)
+result
+```
+
+Use it:
+```bash
+echo "21" | fusion load process.fusion
+```
+
+## Key Concepts
+
+### Ion Data Format
+Fusion uses [Amazon Ion](https://ion-fusion.dev/) as its data format:
+```fusion
+null                    ; Null value
+true false             ; Booleans  
+42 3.14                ; Numbers
+"hello"                ; Strings
+[1, 2, 3]              ; Lists
+{name: "Alice"}        ; Structures (like JSON objects)
+(+ 1 2)                ; S-expressions (function calls)
+```
+
+### Everything is Data
+In Fusion, code is data and data is code:
+```bash
+fusion eval '[1, (+ 2 3), "hello"]'    # Mix data and computation
+```
+
+### Functional Programming
+Functions are first-class values:
+```bash
+fusion eval '(define add (lambda (x y) (+ x y))) (add 10 20)'
+```
+
+## Next Steps
+
+### Learn More Commands
+```bash
+fusion help eval       # Detailed help for eval command
+fusion help load       # Detailed help for load command
+```
+
+### Explore Standard Library
+```bash
+# See what's available
+fusion require '/fusion' ';' repl
+
+# In REPL, try:
+$ (help)               # General help
+$ (help +)             # Help for specific function
+```
+
+### Read the Documentation
+- [Complete CLI Reference](cli_reference.html) - All commands and options
+- [CLI Tutorial](tutorial_cli.html) - Step-by-step learning
+- [Language Reference](fusion.html) - Complete language documentation
+
+### Try Real Examples
+```bash
+# Data transformation
+fusion eval '(map (lambda (x) {value: x, squared: (* x x)}) [1 2 3 4 5])'
+
+# String processing  
+fusion require '/fusion/string' ';' eval '(string_split "a,b,c,d" ",")'
+
+# File processing (create test.ion with some data first)
+echo '[1, 2, 3, 4, 5]' > test.ion
+fusion eval '(define data (with_ion_from_file "test.ion" read)) (fold + 0 data)'
+```
+
+## Getting Help
+
+### Built-in Help
+```bash
+fusion help                    # List all commands
+fusion help <command>          # Detailed command help
+```
+
+### Community
+Visit the [Ion Fusion Community](https://ion-fusion.dev/community/) page for support resources, discussions, and ways to get involved.
+
+### Documentation
+- [CLI Reference](cli_reference.html) - Complete command reference
+- [Language Tutorial](tutorial_cli.html) - Learn the language
+- [Java API](javadoc/index.html) - For embedding in applications
+
+---
+
+**Ready to dive deeper?** Check out the [complete CLI tutorial](tutorial_cli.html) or explore the [language reference](fusion.html).
diff --git a/fusion/src/cli_reference.md b/fusion/src/cli_reference.md
new file mode 100644
index 00000000..3bb39b53
--- /dev/null
+++ b/fusion/src/cli_reference.md
@@ -0,0 +1,497 @@
+<!-- Copyright Ion Fusion contributors. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Ion Fusion CLI Reference
+
+This is the complete reference for the `fusion` command-line interface. The CLI provides powerful tools for evaluating Fusion code, managing modules, and generating reports.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Global Options](#global-options)
+- [Commands](#commands)
+  - [eval](#eval) - Evaluate inline expressions
+  - [load](#load) - Load and execute scripts
+  - [repl](#repl) - Interactive console
+  - [require](#require) - Import module bindings
+  - [report_coverage](#report_coverage) - Generate coverage reports
+  - [help](#help) - Get command help
+  - [version](#version) - Show version information
+- [Command Chaining](#command-chaining)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The `fusion` CLI follows a command/subcommand pattern where you specify one or more commands to execute in sequence. All commands share the same namespace, allowing you to build complex workflows.
+
+**Basic Syntax:**
+```bash
+fusion [GLOBAL_OPTIONS] <command> [ARGS] [; <command> [ARGS]] ...
+```
+
+**Key Features:**
+- Multiple commands can be chained with `;`
+- Commands share a common namespace
+- Supports both interactive and batch processing
+- Built-in help system
+- Comprehensive error reporting
+
+## Global Options
+
+Global options affect the entire CLI execution and must appear before any commands.
+
+### `--repositories DIR[:DIR...]`
+
+Specifies directories containing Fusion modules and resources. This option can be used multiple times, and all directories will be searched for modules.
+
+**Examples:**
+```bash
+fusion --repositories /path/to/modules eval '(require "/mymodule")'
+fusion --repositories /usr/local/fusion:/home/user/fusion-libs load script.fusion
+```
+
+### `--catalogs CATALOG[:CATALOG...]`
+
+Specifies sources of Ion shared symbol tables for efficient data processing. Catalogs can be files containing serialized symbol tables or directories that will be traversed recursively.
+
+**Examples:**
+```bash
+fusion --catalogs catalog.ion eval '(read)'
+fusion --catalogs /usr/share/ion/catalogs:/home/user/catalogs load data-processor.fusion
+```
+
+### `--bootstrapRepository DIR` *(Deprecated)*
+
+**⚠️ DEPRECATED:** This option is deprecated. If used, the directory is treated as the first user repository (equivalent to `--repositories`).
+
+## Commands
+
+### eval
+
+Evaluates Fusion expressions provided as command-line arguments.
+
+**Syntax:** `eval EXPRESSIONS`
+
+**Description:**
+Evaluates the given expressions as top-level Fusion forms. If the result of the last expression is not void, it's written to standard output using Ion format.
+
+**Examples:**
+```bash
+# Simple arithmetic
+fusion eval '(+ 1 2 3)'
+# Output: 6
+
+# Data construction
+fusion eval '{ name: "Alice", age: 30, active: true }'
+# Output: {name:"Alice",age:30,active:true}
+
+# Multiple expressions
+fusion eval '(define x 10) (define y 20) (+ x y)'
+# Output: 30
+
+# Working with lists
+fusion eval '[1, 2, 3, (* 2 2), (+ 3 2)]'
+# Output: [1,2,3,4,5]
+```
+
+**Shell Quoting:**
+Be careful with shell quoting and escaping:
+```bash
+# Good - single quotes protect from shell interpretation
+fusion eval '(define message "Hello World") message'
+
+# Good - escaped double quotes
+fusion eval "(define message \"Hello World\") message"
+
+# Bad - shell will interpret variables and quotes
+fusion eval (define message "Hello $USER") message
+```
+
+**Error Handling:**
+- Empty expressions will show usage information
+- Syntax errors display the problematic location
+- Runtime errors show stack traces with context
+
+### load
+
+Loads and evaluates Fusion scripts from files.
+
+**Syntax:** `load FILE`
+
+**Description:**
+Reads and evaluates a Fusion script from the specified file. The file must be readable and contain valid Fusion code. If the last expression returns a non-void value, it's written to standard output.
+
+**Examples:**
+```bash
+# Load a simple script
+fusion load hello.fusion
+
+# Load with input redirection
+echo "42" | fusion load process-number.fusion
+
+# Load multiple scripts in sequence
+fusion load setup.fusion ';' load main.fusion
+```
+
+**File Requirements:**
+- File must exist and be readable
+- File should contain valid Fusion syntax
+- File path can be relative or absolute
+
+**Sample Script (`hello.fusion`):**
+```fusion
+// Simple greeting script
+(define (greet name)
+  (string_append "Hello, " name "!"))
+
+(greet "World")
+```
+
+**Error Handling:**
+- File not found or not readable will show clear error message
+- Syntax errors in the file will show line numbers and context
+- Runtime errors preserve stack trace information
+
+### repl
+
+Starts an interactive Read-Eval-Print Loop for exploring Fusion interactively.
+
+**Syntax:** `repl`
+
+**Description:**
+Enters an interactive console where you can type Fusion expressions and see results immediately. The REPL maintains state between expressions, allowing you to define variables and functions that persist throughout the session.
+
+**Features:**
+- Colored output (blue for prompts, red for errors)
+- Command history (when using a proper terminal)
+- Built-in help system
+- Graceful error handling
+
+**REPL Commands:**
+```fusion
+(exit)                    ; Exit the REPL
+(help)                    ; Show general help
+(help TOPIC)              ; Show help for specific topic
+```
+
+**Examples:**
+```bash
+$ fusion repl
+
+Welcome to Fusion!
+
+Type...
+  (exit)            to exit
+  (help SOMETHING)  to see documentation; try '(help help)'!
+
+$ (define x 42)
+$ (+ x 8)
+50
+$ (define (factorial n) (if (<= n 1) 1 (* n (factorial (- n 1)))))
+$ (factorial 5)
+120
+$ (exit)
+Goodbye!
+```
+
+**Limitations:**
+- Cannot be used when stdin/stdout are redirected
+- Multi-line expressions must be entered on a single line
+- No line editing features (depends on terminal capabilities)
+
+### require
+
+Imports bindings from Fusion modules into the current namespace.
+
+**Syntax:** `require MODULE_ID`
+
+**Description:**
+Imports all public bindings from the specified module, making them available in the current namespace. This is equivalent to evaluating `(require MODULE_ID)` but more convenient for command-line use.
+
+**Examples:**
+```bash
+# Import string utilities
+fusion require '/fusion/string' ';' eval '(string_length "hello")'
+# Output: 5
+
+# Import and use struct operations
+fusion require '/fusion/struct' ';' eval '(define s (mutable_struct "a" 1)) (put_m s "b" 2) s'
+# Output: {a:1,b:2}
+
+# Chain multiple requires
+fusion require '/fusion/list' ';' require '/fusion/string' ';' eval '(map string_length ["a" "bb" "ccc"])'
+# Output: [1,2,3]
+```
+
+**Module Resolution:**
+- Module IDs are absolute paths starting with `/`
+- Standard library modules are under `/fusion/`
+- User modules depend on repository configuration
+
+**Common Modules:**
+- `/fusion/string` - String manipulation functions
+- `/fusion/list` - List processing utilities
+- `/fusion/struct` - Structure operations
+- `/fusion/io` - Input/output operations
+- `/fusion/number` - Numeric functions
+
+### report_coverage
+
+Generates HTML coverage reports from Fusion code coverage data.
+
+**Syntax:** `report_coverage COVERAGE_DATA_DIR REPORT_DIR`
+
+**Description:**
+Reads code coverage data collected during test runs and generates a comprehensive HTML report showing which lines of code were executed.
+
+**Arguments:**
+- `COVERAGE_DATA_DIR` - Directory containing coverage data files
+- `REPORT_DIR` - Directory where HTML report will be written (created if it doesn't exist)
+
+**Examples:**
+```bash
+# Generate coverage report
+fusion report_coverage build/coverage-data build/reports/coverage
+
+# Using with build system
+./gradlew test
+fusion report_coverage build/fcov build/reports/fcoverage
+```
+
+**Coverage Data:**
+Coverage data is automatically collected when:
+- Running tests with coverage enabled
+- Using `FusionRuntimeBuilder.setCoverageDataDirectory()`
+- Configured via `config.properties` in the data directory
+
+**Report Contents:**
+- Overall coverage statistics
+- Per-file coverage details
+- Line-by-line execution counts
+- Uncovered code highlighting
+
+### help
+
+Displays help information for the CLI or specific commands.
+
+**Syntax:** `help [COMMAND ...]`
+
+**Description:**
+Shows usage information and documentation. Without arguments, displays a list of all available commands. With command names, shows detailed help for those specific commands.
+
+**Examples:**
+```bash
+# Show all commands
+fusion help
+
+# Show help for specific command
+fusion help eval
+
+# Show help for multiple commands
+fusion help eval load repl
+```
+
+**Help Output:**
+- Command syntax and usage
+- Description of functionality
+- Available options and arguments
+- Examples and common patterns
+- Related commands and concepts
+
+### version
+
+Displays version and build information.
+
+**Syntax:** `version`
+
+**Description:**
+Outputs detailed version information in Ion format, including Fusion version, build details, and dependency versions.
+
+**Example:**
+```bash
+fusion version
+```
+
+**Sample Output:**
+```ion
+{
+  fusion_version: {
+    release_label: "0.38a1-SNAPSHOT"
+  },
+  ion_version: {
+    project_version: "1.10.5",
+    build_time: 2024-01-15T10:30:00Z
+  }
+}
+```
+
+## Command Chaining
+
+Multiple commands can be executed in sequence by separating them with semicolons (`;`). All commands share the same namespace, so definitions and imports from earlier commands are available to later ones.
+
+**Syntax:**
+```bash
+fusion command1 args ';' command2 args ';' command3 args
+```
+
+**Shell Escaping:**
+In most shells, semicolons need to be escaped or quoted:
+```bash
+# Escaped semicolon
+fusion require /fusion/string \; eval '(string_length "test")'
+
+# Quoted semicolon
+fusion require /fusion/string ';' eval '(string_length "test")'
+```
+
+**Examples:**
+```bash
+# Setup and execution
+fusion require '/fusion/list' ';' eval '(define nums [1 2 3 4 5])' ';' eval '(fold + 0 nums)'
+
+# Load configuration then run script
+fusion load config.fusion ';' load main.fusion
+
+# Interactive session with preloaded modules
+fusion require '/fusion/string' ';' require '/fusion/list' ';' repl
+```
+
+**Namespace Sharing:**
+- Variables defined in one command are available in subsequent commands
+- Module imports persist across commands
+- Error in one command stops execution of remaining commands
+
+## Examples
+
+### Data Processing Pipeline
+
+Process JSON data through multiple transformation steps:
+
+```bash
+# Process JSON data with transformations
+echo '{"users": [{"name": "Alice", "age": 25}, {"name": "Bob", "age": 30}]}' | \
+fusion eval '(define data (read))' ';' \
+       eval '(define users (. data "users"))' ';' \
+       eval '(map (lambda (user) (. user "name")) users)'
+```
+
+### Module Development Workflow
+
+Develop and test a custom module:
+
+```bash
+# Load module and test interactively
+fusion --repositories ./my-modules require '/myproject/utils' ';' repl
+
+# Run tests with coverage
+fusion --repositories ./my-modules load test-suite.fusion ';' \
+       report_coverage ./coverage-data ./coverage-report
+```
+
+### Batch Processing
+
+Process multiple files with the same script:
+
+```bash
+# Process each file in a directory
+for file in data/*.ion; do
+  echo "Processing $file"
+  fusion load process-data.fusion < "$file" > "processed/$(basename "$file")"
+done
+```
+
+### Configuration and Execution
+
+Load configuration and run application:
+
+```bash
+# Production deployment
+fusion --repositories /opt/fusion-modules \
+       --catalogs /opt/ion-catalogs \
+       load config/production.fusion ';' \
+       load app/main.fusion
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Command Not Found**
+```
+fusion: command not found
+```
+- Ensure `fusion` is in your PATH
+- Check installation was successful
+- Try using full path to binary
+
+**Module Not Found**
+```
+Bad syntax: unbound identifier. The symbol 'my_function' has no binding
+```
+- Check if module was imported with `require`
+- Verify module path is correct
+- Ensure module repository is configured with `--repositories`
+
+**File Not Readable**
+```
+Script is not a readable file: script.fusion
+```
+- Check file exists and has correct permissions
+- Verify file path is correct (relative vs absolute)
+- Ensure file contains valid Fusion syntax
+
+**Syntax Errors**
+```
+Bad syntax: unexpected token
+```
+- Check parentheses are balanced
+- Verify string quotes are properly closed
+- Review Ion syntax requirements
+
+**Memory Issues**
+```
+OutOfMemoryError
+```
+- Increase JVM heap size: `JAVA_OPTS="-Xmx2g" fusion ...`
+- Process data in smaller chunks
+- Check for infinite loops or recursion
+
+### Performance Tips
+
+**Large Data Processing:**
+- Use streaming operations when possible
+- Process data in chunks rather than loading everything into memory
+- Use efficient operations like struct lookups with `elt` over nested access with `.`
+
+**Module Loading:**
+- Organize modules efficiently to minimize loading time
+- Use specific imports rather than importing entire modules
+- Cache frequently used modules in repositories
+
+**REPL Usage:**
+- Define frequently used functions in startup scripts
+- Use `load` to bring in utility functions
+- Keep REPL sessions focused to avoid memory buildup
+
+### Getting Help
+
+**Built-in Help:**
+```bash
+fusion help                    # List all commands
+fusion help <command>          # Detailed command help
+```
+
+**Community Resources:**
+- [GitHub Issues](https://github.com/ion-fusion/fusion-java/issues)
+- [Discussion Forums](https://github.com/orgs/ion-fusion/discussions)
+- [Slack Workspace](https://join.slack.com/t/ion-fusion/shared_invite/zt-2y0jr8vh2-bZLa66hdyZ3ykHcgOcYkcA)
+
+**Documentation:**
+- [Language Reference](fusion.html)
+- [Java API Documentation](javadoc/index.html)
+- [Tutorial](tutorial_cli.html)
+
+---
+
+*For more information about the Ion Fusion language itself, see the [Language Reference](fusion.html).*
diff --git a/fusion/src/cli_troubleshooting.md b/fusion/src/cli_troubleshooting.md
new file mode 100644
index 00000000..fe9fe134
--- /dev/null
+++ b/fusion/src/cli_troubleshooting.md
@@ -0,0 +1,636 @@
+<!-- Copyright Ion Fusion contributors. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Ion Fusion CLI Troubleshooting Guide
+
+This guide helps you diagnose and fix common issues when using the Ion Fusion CLI. If you don't find your issue here, please check our [community resources](#getting-help) for additional support.
+
+## Table of Contents
+
+- [Installation Issues](#installation-issues)
+- [Command Execution Problems](#command-execution-problems)
+- [Syntax and Runtime Errors](#syntax-and-runtime-errors)
+- [Module and Import Issues](#module-and-import-issues)
+- [Performance Problems](#performance-problems)
+- [File and Path Issues](#file-and-path-issues)
+- [REPL Issues](#repl-issues)
+- [Environment and Configuration](#environment-and-configuration)
+- [Getting Help](#getting-help)
+
+## Installation Issues
+
+### Command Not Found
+
+**Problem:**
+```bash
+$ fusion help
+fusion: command not found
+```
+
+**Solutions:**
+
+1. **Check if `fusion` is in your PATH:**
+   ```bash
+   which fusion
+   echo $PATH
+   ```
+
+2. **If you built from source, add to PATH:**
+   ```bash
+   export PATH=$PATH:/path/to/fusion-java/build/install/fusion/bin
+   # Add to your shell profile (.bashrc, .zshrc, etc.) to make permanent
+   ```
+
+3. **Verify the binary exists and is executable:**
+   ```bash
+   ls -la /path/to/fusion/bin/fusion
+   chmod +x /path/to/fusion/bin/fusion  # If not executable
+   ```
+
+4. **Try using the full path:**
+   ```bash
+   /path/to/fusion/bin/fusion help
+   ```
+
+### Java Runtime Issues
+
+**Problem:**
+```bash
+$ fusion help
+Error: Could not find or load main class dev.ionfusion.fusion.cli.Cli
+```
+
+**Solutions:**
+
+1. **Check Java installation:**
+   ```bash
+   java -version
+   which java
+   ```
+
+2. **Ensure Java 8 or later is installed:**
+   ```bash
+   # Install Corretto (recommended)
+   # macOS with Homebrew:
+   brew install --cask corretto8
+   
+   # macOS with MacPorts:
+   sudo port install openjdk8-corretto
+   
+   # Ubuntu/Debian (OpenJDK):
+   sudo apt-get install openjdk-8-jdk
+   
+   # Ubuntu/Debian (Corretto):
+   wget -O- https://apt.corretto.aws/corretto.key | sudo apt-key add -
+   sudo add-apt-repository 'deb https://apt.corretto.aws stable main'
+   sudo apt-get update
+   sudo apt-get install java-1.8.0-amazon-corretto-jdk
+   ```
+
+3. **Check JAVA_HOME environment variable:**
+   ```bash
+   echo $JAVA_HOME
+   export JAVA_HOME=/path/to/java
+   ```
+
+### Build Issues
+
+**Problem:**
+```bash
+$ ./gradlew release
+BUILD FAILED
+```
+
+**Solutions:**
+
+1. **Check Java version for building:**
+   ```bash
+   java -version  # Should be Java 8 or later
+   ```
+
+2. **Clean and rebuild:**
+   ```bash
+   ./gradlew clean
+   ./gradlew release
+   ```
+
+3. **Check for network issues (if downloading dependencies):**
+   ```bash
+   ./gradlew --offline release  # Try offline build
+   ```
+
+4. **Check disk space:**
+   ```bash
+   df -h .
+   ```
+
+## Command Execution Problems
+
+### General Usage Errors
+
+**Problem:**
+```bash
+$ fusion
+No command given.
+Type 'fusion help' for more information.
+```
+
+**Solution:**
+Always specify a command:
+```bash
+fusion help           # Show available commands
+fusion eval '(+ 1 2)' # Evaluate an expression
+fusion repl           # Start interactive mode
+```
+
+### Invalid Command Arguments
+
+**Problem:**
+```bash
+$ fusion eval
+Usage: eval EXPRESSIONS
+Type 'fusion help eval' for more information.
+```
+
+**Solution:**
+Provide required arguments:
+```bash
+fusion eval '(+ 1 2)'              # Correct
+fusion help eval                   # Get detailed help
+```
+
+### Shell Quoting Issues
+
+**Problem:**
+```bash
+$ fusion eval (+ 1 2)
+bash: syntax error near unexpected token `('
+```
+
+**Solutions:**
+
+1. **Use single quotes (recommended):**
+   ```bash
+   fusion eval '(+ 1 2)'
+   ```
+
+2. **Use double quotes with escaping:**
+   ```bash
+   fusion eval "(+ 1 2)"
+   ```
+
+3. **Escape special characters:**
+   ```bash
+   fusion eval \(+ 1 2\)
+   ```
+
+### Command Chaining Problems
+
+**Problem:**
+```bash
+$ fusion require /fusion/string ; eval '(string_length "test")'
+bash: eval: command not found
+```
+
+**Solution:**
+Quote or escape the semicolon:
+```bash
+fusion require /fusion/string ';' eval '(string_length "test")'
+# OR
+fusion require /fusion/string \; eval '(string_length "test")'
+```
+
+## Syntax and Runtime Errors
+
+### Unbalanced Parentheses
+
+**Problem:**
+```bash
+$ fusion eval '(+ 1 2'
+Bad syntax: unexpected end of input
+```
+
+**Solution:**
+Ensure all parentheses are balanced:
+```bash
+fusion eval '(+ 1 2)'  # Correct
+```
+
+### Unbound Identifier
+
+**Problem:**
+```bash
+$ fusion eval '(string_length "hello")'
+Bad syntax: unbound identifier. The symbol 'string_length' has no binding
+```
+
+**Solutions:**
+
+1. **Import the required module:**
+   ```bash
+   fusion require '/fusion/string' ';' eval '(string_length "hello")'
+   ```
+
+2. **Check spelling and case sensitivity:**
+   ```bash
+   fusion eval '(string_append "a" "b")'  # Built-in function
+   ```
+
+3. **Use built-in functions when available:**
+   ```bash
+   fusion eval '(+ 1 2)'  # Math functions are built-in
+   ```
+
+### Type Errors
+
+**Problem:**
+```bash
+$ fusion eval '(+ "hello" 5)'
+Argument error: + expects number, got string "hello"
+```
+
+**Solution:**
+Ensure arguments match expected types:
+```bash
+fusion eval '(+ 5 3)'                    # Numbers
+fusion eval '(string_append "hello" "5")' # Strings
+```
+
+### Arity Errors
+
+**Problem:**
+```bash
+$ fusion eval '(+ 1)'
+Arity error: + expects at least 2 arguments, got 1
+```
+
+**Solution:**
+Provide the correct number of arguments:
+```bash
+fusion eval '(+ 1 2)'      # Correct
+fusion eval '(+ 1 2 3 4)'  # Also correct (variadic)
+```
+
+## Module and Import Issues
+
+### Module Not Found
+
+**Problem:**
+```bash
+$ fusion require '/mymodule'
+Module not found: /mymodule
+```
+
+**Solutions:**
+
+1. **Check module path spelling:**
+   ```bash
+   fusion require '/fusion/string'  # Standard library module
+   ```
+
+2. **Use repository option for custom modules:**
+   ```bash
+   fusion --repositories /path/to/modules require '/mymodule'
+   ```
+
+3. **List available modules:**
+   ```bash
+   fusion require '/fusion' ';' repl
+   $ (help)  # In REPL, shows available functions
+   ```
+
+### Repository Configuration
+
+**Problem:**
+```bash
+$ fusion --repositories /nonexistent require '/mymodule'
+repositories: Directory does not exist: /nonexistent
+```
+
+**Solutions:**
+
+1. **Check directory exists:**
+   ```bash
+   ls -la /path/to/modules
+   ```
+
+2. **Use absolute paths:**
+   ```bash
+   fusion --repositories /absolute/path/to/modules require '/mymodule'
+   ```
+
+3. **Use multiple repositories:**
+   ```bash
+   fusion --repositories /path1:/path2 require '/mymodule'
+   ```
+
+## Performance Problems
+
+### Slow Startup
+
+**Problem:**
+CLI takes a long time to start.
+
+**Solutions:**
+
+1. **Check available memory:**
+   ```bash
+   free -h  # Linux
+   vm_stat  # macOS
+   ```
+
+2. **Increase JVM heap size:**
+   ```bash
+   export JAVA_OPTS="-Xmx2g"
+   fusion eval '(+ 1 2)'
+   ```
+
+3. **Use SSD storage if possible**
+
+4. **Check for antivirus interference**
+
+### Memory Issues
+
+**Problem:**
+```bash
+$ fusion eval '(very-large-computation)'
+Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
+```
+
+**Solutions:**
+
+1. **Increase heap size:**
+   ```bash
+   export JAVA_OPTS="-Xmx4g"
+   fusion eval '(your-expression)'
+   ```
+
+2. **Process data in chunks:**
+   ```bash
+   # Instead of loading all data at once
+   fusion eval '(for [(item (in_port))] (process-item item))'
+   ```
+
+3. **Use streaming operations:**
+   ```bash
+   # Stream processing instead of collecting all results
+   cat large-file.ion | fusion eval '(for [(item (in_port))] (writeln (process item)))'
+   ```
+
+### Slow Data Processing
+
+**Problem:**
+Data processing is slower than expected.
+
+**Solutions:**
+
+1. **Use efficient Fusion operations:**
+   ```bash
+   # Use struct lookups with elt over nested access
+   fusion eval '(elt data "field")' # instead of (. data "field")
+   ```
+
+2. **Avoid deeply nested loops:**
+   ```bash
+   # Use built-in functions when possible
+   fusion require '/fusion/list' ';' eval '(map process-fn data)'
+   ```
+
+3. **Optimize algorithms:**
+   ```bash
+   # Use performant operations like struct lookups
+   fusion require '/fusion/struct' ';' eval '(struct_get data "key")'
+   ```
+
+3. **Profile with coverage tools:**
+   ```bash
+   fusion --repositories ./modules load --profile script.fusion
+   ```
+
+## File and Path Issues
+
+### File Not Found
+
+**Problem:**
+```bash
+$ fusion load script.fusion
+Script is not a readable file: script.fusion
+```
+
+**Solutions:**
+
+1. **Check file exists:**
+   ```bash
+   ls -la script.fusion
+   ```
+
+2. **Check file permissions:**
+   ```bash
+   chmod +r script.fusion
+   ```
+
+3. **Use absolute path:**
+   ```bash
+   fusion load /absolute/path/to/script.fusion
+   ```
+
+4. **Check current directory:**
+   ```bash
+   pwd
+   ls *.fusion
+   ```
+
+### Permission Denied
+
+**Problem:**
+```bash
+$ fusion load script.fusion
+Permission denied: script.fusion
+```
+
+**Solutions:**
+
+1. **Fix file permissions:**
+   ```bash
+   chmod +r script.fusion
+   ```
+
+2. **Check directory permissions:**
+   ```bash
+   ls -la .
+   chmod +rx .  # If directory not readable/executable
+   ```
+
+3. **Run with appropriate user:**
+   ```bash
+   sudo fusion load script.fusion  # If necessary (not recommended)
+   ```
+
+## REPL Issues
+
+### REPL Won't Start
+
+**Problem:**
+```bash
+$ fusion repl
+This command cannot be used when stdin or stdout have been redirected.
+```
+
+**Solution:**
+Don't redirect stdin/stdout when using REPL:
+```bash
+# Wrong:
+echo "test" | fusion repl
+
+# Correct:
+fusion repl
+```
+
+### REPL Display Issues
+
+**Problem:**
+Colors or formatting look wrong in REPL.
+
+**Solutions:**
+
+1. **Check terminal capabilities:**
+   ```bash
+   echo $TERM
+   ```
+
+2. **Use a modern terminal:**
+   - Terminal.app (macOS)
+   - GNOME Terminal (Linux)
+   - Windows Terminal (Windows)
+
+3. **Disable colors if needed:**
+   ```bash
+   export NO_COLOR=1
+   fusion repl
+   ```
+
+### REPL History Issues
+
+**Problem:**
+Arrow keys don't work for command history.
+
+**Solutions:**
+
+1. **Use a terminal with line editing support**
+
+2. **Install readline support for Java**
+
+3. **Use external tools:**
+   ```bash
+   rlwrap fusion repl  # If rlwrap is available
+   ```
+
+## Environment and Configuration
+
+### Environment Variables
+
+**Common environment variables:**
+
+```bash
+# Java options
+export JAVA_OPTS="-Xmx2g -XX:+UseG1GC"
+
+# Disable colors
+export NO_COLOR=1
+
+# Custom Java home
+export JAVA_HOME=/path/to/java
+
+# Additional classpath
+export CLASSPATH="/path/to/additional/jars:$CLASSPATH"
+```
+
+### Configuration Files
+
+**Check for configuration issues:**
+
+1. **Coverage configuration:**
+   ```bash
+   cat build/fcov/config.properties
+   ```
+
+2. **Repository structure:**
+   ```bash
+   find /path/to/repositories -name "*.fusion" | head -10
+   ```
+
+### Debugging Options
+
+**Enable debugging:**
+
+```bash
+# Verbose Java output
+export JAVA_OPTS="-verbose:class -verbose:gc"
+
+# Enable assertions
+export JAVA_OPTS="-ea"
+
+# Debug class loading
+export JAVA_OPTS="-XX:+TraceClassLoading"
+```
+
+## Getting Help
+
+### Built-in Help
+
+```bash
+fusion help                    # List all commands
+fusion help <command>          # Detailed command help
+fusion version                 # Version information
+```
+
+### REPL Help
+
+```fusion
+$ (help)                      # General help
+$ (help +)                    # Help for specific function
+$ (help "string")             # Search help
+```
+
+### Community Resources
+
+- **[GitHub Issues](https://github.com/ion-fusion/fusion-java/issues)** - Bug reports and feature requests
+- **[GitHub Discussions](https://github.com/orgs/ion-fusion/discussions)** - Questions and community help
+- **[Slack Workspace](https://join.slack.com/t/ion-fusion/shared_invite/zt-2y0jr8vh2-bZLa66hdyZ3ykHcgOcYkcA)** - Real-time chat support
+
+### Reporting Issues
+
+When reporting issues, please include:
+
+1. **Fusion version:**
+   ```bash
+   fusion version
+   ```
+
+2. **Java version:**
+   ```bash
+   java -version
+   ```
+
+3. **Operating system:**
+   ```bash
+   uname -a  # Linux/macOS
+   ver       # Windows
+   ```
+
+4. **Complete error message**
+
+5. **Minimal reproduction case**
+
+6. **Steps to reproduce**
+
+### Documentation
+
+- **[CLI Reference](cli_reference.html)** - Complete command reference
+- **[CLI Tutorial](tutorial_cli.html)** - Step-by-step learning guide
+- **[Language Reference](fusion.html)** - Fusion language documentation
+- **[Java API](javadoc/index.html)** - For embedding applications
+
+---
+
+*If your issue isn't covered here, please don't hesitate to reach out to the community for help!*
diff --git a/fusion/src/howto_build.md b/fusion/src/howto_build.md
index 85c98c52..48c54799 100644
--- a/fusion/src/howto_build.md
+++ b/fusion/src/howto_build.md
@@ -1,41 +1,371 @@
 <!-- Copyright Ion Fusion contributors. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# Building Ion Fusion
+# Installing and Building Ion Fusion
 
-> **Prerequisites:**
->
-> * Install a Java runtime, version 8 or later. We recommend [Amazon Corretto][].
-> * Install [Git][].
-> * Ensure that `java` and `git` are on your shell's `PATH`.
+This guide covers multiple ways to install Ion Fusion, from building from source to using pre-built distributions.
 
-Building from source should be straightforward:
+## Table of Contents
 
-    git clone https://github.com/ion-fusion/fusion-java.git
-    cd fusion-java
-    ./gradlew release
+- [Quick Start](#quick-start)
+- [Installation Methods](#installation-methods)
+- [Building from Source](#building-from-source)
+- [Verification](#verification)
+- [Troubleshooting](#troubleshooting)
+- [What's Next](#whats-next)
 
-After a successful release build, you'll have a basic SDK under `build/install/fusion`. The notable
-artifacts within that directory are:
+## Quick Start
 
-* `bin/fusion` is the `fusion` CLI
-* `docs/fusiondoc/fusion.html` is the documentation for the Ion Fusion language
-* `docs/javadoc/index.html` is the documentation embedding Ion Fusion in your Java application
-* `lib` holds the jars needed for embedding
+**For most users, building from source is currently the recommended approach:**
 
-To experiment with the CLI, add the `bin` to your path:
+```bash
+# Clone and build
+git clone https://github.com/ion-fusion/fusion-java.git
+cd fusion-java
+./gradlew release
 
-    PATH=$PATH:$PWD/build/install/fusion/bin
-    fusion help
+# Add to PATH
+export PATH=$PATH:$PWD/build/install/fusion/bin
 
-That should give you an overview of the CLI's subcommands.
+# Verify installation
+fusion version
+```
 
+## Installation Methods
+
+### Method 1: Build from Source (Recommended)
+
+**Prerequisites:**
+- Java 8 or later ([Corretto](https://aws.amazon.com/corretto/) recommended)
+- [Git](https://git-scm.com/)
+- Internet connection (for downloading dependencies)
+
+**Advantages:**
+- Always get the latest version
+- Can customize the build
+- Full control over the installation
+
+**Steps:**
+
+1. **Install Prerequisites:**
+   ```bash
+   # macOS with Homebrew
+   brew install --cask corretto8
+   brew install git
+   
+   # Ubuntu/Debian
+   sudo apt-get update
+   sudo apt-get install openjdk-8-jdk git
+   
+   # CentOS/RHEL/Fedora
+   sudo yum install java-1.8.0-openjdk-devel git  # CentOS/RHEL
+   sudo dnf install java-1.8.0-openjdk-devel git  # Fedora
+   ```
+
+2. **Verify Java Installation:**
+   ```bash
+   java -version
+   # Should show Java 8 or later
+   ```
+
+3. **Clone and Build:**
+   ```bash
+   git clone https://github.com/ion-fusion/fusion-java.git
+   cd fusion-java
+   ./gradlew release
+   ```
+
+4. **Install to PATH:**
+   ```bash
+   # Temporary (current session only)
+   export PATH=$PATH:$PWD/build/install/fusion/bin
+   
+   # Permanent (add to your shell profile)
+   echo 'export PATH=$PATH:/path/to/fusion-java/build/install/fusion/bin' >> ~/.bashrc
+   # OR for zsh:
+   echo 'export PATH=$PATH:/path/to/fusion-java/build/install/fusion/bin' >> ~/.zshrc
+   ```
+
+### Method 2: Pre-built Releases *(Coming Soon)*
+
+Pre-built binaries will be available from the [GitHub releases page](https://github.com/ion-fusion/fusion-java/releases) once version 1.0 is released.
+
+**Planned distribution formats:**
+- Standalone JAR files
+- Platform-specific installers
+- Docker containers
+- Package manager distributions (Homebrew, apt, etc.)
+
+### Method 3: Docker *(Future)*
+
+Docker images will be available for easy containerized deployment:
+
+```bash
+# Planned usage (not yet available)
+docker run -it ion-fusion/fusion:latest repl
+```
+
+## Building from Source
+
+### Standard Build
+
+The standard build creates a complete SDK with CLI, documentation, and libraries:
+
+```bash
+./gradlew release
+```
+
+**Build artifacts:**
+- `build/install/fusion/bin/fusion` - CLI executable
+- `build/install/fusion/lib/` - JAR files for embedding
+- `build/install/fusion/docs/fusiondoc/` - Language documentation
+- `build/install/fusion/docs/javadoc/` - Java API documentation
+
+### Development Build
+
+For development and testing:
+
+```bash
+./gradlew build
+```
+
+This creates a faster build without full documentation generation.
+
+### Custom Build Options
+
+**Clean build:**
+```bash
+./gradlew clean release
+```
+
+**Build with specific Java version:**
+```bash
+export JAVA_HOME=/path/to/java8
+./gradlew release
+```
+
+**Offline build (if dependencies already cached):**
+```bash
+./gradlew --offline release
+```
+
+**Parallel build (faster on multi-core systems):**
+```bash
+./gradlew --parallel release
+```
+
+### Build Requirements
+
+**System Requirements:**
+- **Memory:** At least 2GB RAM (4GB recommended)
+- **Disk Space:** At least 1GB free space
+- **Network:** Internet connection for downloading dependencies (first build only)
+
+**Java Requirements:**
+- **Version:** Java 8 or later (Java 11+ recommended for better performance)
+- **Distribution:** Any OpenJDK distribution (Corretto, AdoptOpenJDK, etc.)
+
+### Build Troubleshooting
+
+**Common Issues:**
+
+1. **Out of Memory:**
+   ```bash
+   export GRADLE_OPTS="-Xmx2g"
+   ./gradlew release
+   ```
+
+2. **Network Issues:**
+   ```bash
+   # Try with different repository
+   ./gradlew --refresh-dependencies release
+   ```
+
+3. **Permission Issues:**
+   ```bash
+   chmod +x gradlew
+   ./gradlew release
+   ```
+
+4. **Java Version Issues:**
+   ```bash
+   # Check Java version
+   java -version
+   javac -version
+   
+   # Set specific Java version
+   export JAVA_HOME=/path/to/correct/java
+   ```
+
+## Verification
+
+### Verify Installation
+
+```bash
+# Check CLI is available
+fusion help
+
+# Check version information
+fusion version
+
+# Test basic functionality
+fusion eval '(+ 1 2 3)'
+# Should output: 6
+```
+
+### Verify Build Artifacts
+
+```bash
+# Check CLI executable
+ls -la build/install/fusion/bin/fusion
+
+# Check libraries
+ls -la build/install/fusion/lib/
+
+# Check documentation
+ls -la build/install/fusion/docs/
+```
+
+### Run Tests
+
+```bash
+# Run all tests
+./gradlew test
+
+# Run specific test suite
+./gradlew test --tests "*CliTest*"
+
+# Run with coverage
+./gradlew test jacocoTestReport
+```
+
+## Advanced Installation
+
+### System-wide Installation
+
+**Linux/macOS:**
+```bash
+# Copy to system location
+sudo cp -r build/install/fusion /opt/
+sudo ln -s /opt/fusion/bin/fusion /usr/local/bin/fusion
+
+# Or create a package
+./gradlew distTar
+# Extract tar to desired location
+```
+
+**Windows:**
+```cmd
+# Copy to Program Files
+xcopy build\install\fusion "C:\Program Files\Ion-Fusion\" /E /I
+
+# Add to PATH via System Properties or:
+setx PATH "%PATH%;C:\Program Files\Ion-Fusion\bin"
+```
+
+### IDE Integration
+
+**IntelliJ IDEA:**
+1. Import the Gradle project
+2. Set Project SDK to Java 8+
+3. Enable annotation processing
+4. Configure code style (see `doc/draft/style_guide.md`)
+
+**Eclipse:**
+1. Import as Gradle project
+2. Configure Java Build Path
+3. Set up code formatting
+
+**VS Code:**
+1. Install Java Extension Pack
+2. Open project folder
+3. Configure Java runtime
+
+### Custom Repositories
+
+For organizations wanting to customize Fusion:
+
+```bash
+# Fork the repository
+git clone https://github.com/yourorg/fusion-java.git
+cd fusion-java
+
+# Make customizations
+# ... edit source files ...
+
+# Build custom version
+./gradlew release
+
+# Create custom distribution
+./gradlew distTar distZip
+```
+
+## Troubleshooting
+
+### Build Failures
+
+**Gradle daemon issues:**
+```bash
+./gradlew --stop
+./gradlew release
+```
+
+**Dependency resolution:**
+```bash
+./gradlew --refresh-dependencies clean release
+```
+
+**Disk space:**
+```bash
+df -h .
+./gradlew clean  # Free up space
+```
+
+### Runtime Issues
+
+**Java not found:**
+```bash
+which java
+export JAVA_HOME=/path/to/java
+export PATH=$JAVA_HOME/bin:$PATH
+```
+
+**Permission denied:**
+```bash
+chmod +x build/install/fusion/bin/fusion
+```
+
+**Library conflicts:**
+```bash
+# Check for conflicting JARs
+java -cp "build/install/fusion/lib/*" -version
+```
+
+### Getting Help
+
+If you encounter issues:
+
+1. **Check the [troubleshooting guide](cli_troubleshooting.html)**
+2. **Search [existing issues](https://github.com/ion-fusion/fusion-java/issues)**
+3. **Ask on [GitHub Discussions](https://github.com/orgs/ion-fusion/discussions)**
+4. **Join our [Slack workspace](https://join.slack.com/t/ion-fusion/shared_invite/zt-2y0jr8vh2-bZLa66hdyZ3ykHcgOcYkcA)**
 
 ## What's Next?
 
-With the `fusion` CLI ready to go, you can follow the [CLI tutorial](tutorial_cli.html) and run
-some code!
+With Ion Fusion installed, you're ready to start coding:
+
+### Learn the CLI
+- **[CLI Quick Start](cli_quickstart.html)** - Get productive in minutes
+- **[CLI Tutorial](tutorial_cli.html)** - Comprehensive learning guide
+- **[CLI Reference](cli_reference.html)** - Complete command documentation
+
+### Explore the Language
+- **[Language Reference](fusion.html)** - Complete language documentation
+- **[Java API](javadoc/index.html)** - For embedding in applications
 
+### Join the Community
+- **[GitHub](https://github.com/ion-fusion/fusion-java)** - Source code and issues
+- **[Slack](https://join.slack.com/t/ion-fusion/shared_invite/zt-2y0jr8vh2-bZLa66hdyZ3ykHcgOcYkcA)** - Community chat
+- **[Discussions](https://github.com/orgs/ion-fusion/discussions)** - Questions and help
 
-[Amazon Corretto]: https://aws.amazon.com/corretto
-[Git]: https://git-scm.com/
+Happy coding with Ion Fusion!
diff --git a/fusion/src/index.md b/fusion/src/index.md
index 212c8c70..85fefafe 100644
--- a/fusion/src/index.md
+++ b/fusion/src/index.md
@@ -14,19 +14,25 @@ questions, requests, or other feedback, please post to our [Discussion boards][d
 [new-issue]: https://github.com/ion-fusion/fusion-java/issues/new
 
 
-## Tutorials
+## Getting Started
+
+* **[CLI Quick Start](cli_quickstart.html)** - Get productive with Fusion in minutes
+* **[Installation Guide](howto_build.html)** - Install Ion Fusion on your system
 
-* Get started by trying out [the `fusion` CLI](tutorial_cli.html).
+## Tutorials
 
+* **[CLI Tutorial](tutorial_cli.html)** - Comprehensive guide to using the Fusion CLI
+* **[Language Tutorial](fusion.html)** - Learn the Fusion programming language
 
 ## How-to Guides
 
-* [How to Build Ion Fusion](howto_build.html)
-
+* **[CLI Reference](cli_reference.html)** - Complete command-line reference
+* **[CLI Troubleshooting](cli_troubleshooting.html)** - Solve common CLI issues
+* **[Installation Guide](howto_build.html)** - Build and install from source
 
 ## Explanation
 
-* [About the `fusion` CLI](about_cli.html)
+* **[About the CLI](about_cli.html)** - Understanding the Fusion command-line interface
 
 
 ## Reference
diff --git a/fusion/src/tutorial_cli.md b/fusion/src/tutorial_cli.md
index 6e44f018..d580c595 100644
--- a/fusion/src/tutorial_cli.md
+++ b/fusion/src/tutorial_cli.md
@@ -3,97 +3,457 @@
 
 # Tutorial: Exploring the Fusion CLI
 
-Here we'll walk through some basic use cases with Ion Fusion's command-line interface.
-
-> **Prerequisites:** 
->
-> * Install a Java runtime, version 8 or later. We recommend [Amazon Corretto][].
-> * Ensure that `java` is on your shell's `PATH`.
-> * Download the [Ion Fusion SDK][SDK], unpack it somewhere, and add its
->   `bin` directory to your `PATH`.
->
-> Alternatively, you can [build the CLI from source](howto_build.html).
-
-The `fusion` CLI has three modes of operation: an interactive REPL, script execution, and direct
-evaluation of expressions. We'll start with the latter:
-
-    fusion eval '(+ 1 2)'
-
-That should print `3`.  What's not obvious is that the evaluator is printing the result in
-Amazon Ion format.  We can use a more interesting expression to demonstrate:
-
-    fusion eval '[null, (timestamp_at_day 2025-03-28T02:09-07:00)]'
-
-That should print `[null, 2025-03-28]`, using Ion's notation for a timestamp. You can see that the
-list in the input expression evaluates to list, and each element of the list is likewise evaluated
-as an expression. Fusion makes it easy to construct data very directly. This applies to Ion structs
-(JSON objects) as well:
-
-    fusion eval '{ name: "John Doe", date: 2001-03-27, score: (* 7 3) }'
-
-That should print `{name:"John Doe", date:2001-03-27, score:21}` (though the whitespace and field
-order may differ).
-
-> **TIP:**
-> Ion Fusion uses the Amazon Ion data format as its concrete syntax, leveraging Ion's [symbol][]
-> and [S-expression][sexp] types in a Lisp-like style. Put another way, Fusion source code _is_
-> Ion data. In general, when a data element isn't an Ion S-expression or symbol, it evaluates to
-> itself!
-
-As our last example for now, we'll demonstrate a nontrivial Fusion script: generate a list of
-authors to this repository, in chronological order. This real-world example was used to generate the
-list in our [CONTRIBUTORS][] page.
-
-First, copy this content into a file named `authors.fusion`:
-
-
-    (define all_names
-      '''
-    A sexp (linked list) containing all the values on the
-    current input stream.
-      '''
-      (series_to_sexp (in_port)))
-    
-    (define (deduplicate s)
-      '''
-    Remove duplicate values from sexp `s`, keeping the _last_
-    copy of any duplicates.
-      '''
-      (if (is_empty s) s
-        // Decompose the sexp into its head/tail (aka car/cdr).
-        (let [(name   (head s)),
-              (others (tail s))]
-          (if (any (|n| (== n name)) others)
-            // The name is in the tail, so ignore this copy.
-            (deduplicate others)
-            // The name is not in the tail, so keep it and
-            // dedup the tail.
-            (pair name (deduplicate others))))))
-    
-    // Print the deduplicated names in chrono order, one per line.
-    (for [(name (reverse (deduplicate all_names)))]
-      (displayln name))
-
-
-Now, run the script over the output of `git log`:
-
-    git log --pretty=format:'"%an"' | fusion load authors.fusion
-
-You'll see the deduplicated names, one per line, in order of their first commit. This isn't
-necessarily the easiest way to accomplish this task, but it demonstrates the use of Fusion for
-ad-hoc data processing.
+This comprehensive tutorial will teach you how to use the Ion Fusion command-line interface effectively. We'll cover all major features with practical examples and real-world use cases.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Basic Expression Evaluation](#basic-expression-evaluation)
+- [Working with Data](#working-with-data)
+- [Script Execution](#script-execution)
+- [Interactive Development](#interactive-development)
+- [Module System](#module-system)
+- [Command Chaining](#command-chaining)
+- [Data Processing Workflows](#data-processing-workflows)
+- [Advanced Features](#advanced-features)
+- [What's Next](#whats-next)
+
+## Prerequisites
+
+**Installation Options:**
+
+**Option 1: Build from Source (Recommended)**
+```bash
+git clone https://github.com/ion-fusion/fusion-java.git
+cd fusion-java
+./gradlew release
+export PATH=$PATH:$PWD/build/install/fusion/bin
+```
+
+**Option 2: Pre-built SDK** *(Coming Soon)*
+- Download the [Ion Fusion SDK][SDK] when available
+- Unpack and add `bin` directory to your `PATH`
+
+**Requirements:**
+- Java runtime, version 8 or later ([Corretto][] recommended)
+- `java` must be on your shell's `PATH`
+
+**Verify Installation:**
+```bash
+fusion version
+fusion help
+```
+
+## Basic Expression Evaluation
+
+The `fusion` CLI has multiple modes of operation. Let's start with direct evaluation of expressions using the `eval` command:
+
+```bash
+fusion eval '(+ 1 2)'
+```
+**Output:** `3`
+
+The result is printed in Amazon Ion format. Let's try more interesting expressions:
+
+```bash
+# Working with timestamps
+fusion eval '[null, (timestamp_at_day 2025-03-28T02:09-07:00)]'
+```
+**Output:** `[null, 2025-03-28]`
+
+```bash
+# Arithmetic in data structures
+fusion eval '{ name: "John Doe", date: 2001-03-27, score: (* 7 3) }'
+```
+**Output:** `{name:"John Doe", date:2001-03-27, score:21}`
+
+```bash
+# String operations
+fusion eval '(string_append "Hello, " "World!")'
+```
+**Output:** `"Hello, World!"`
+
+> **Key Concept:**
+> Ion Fusion uses Amazon Ion as its concrete syntax, leveraging Ion's [symbol][] and [S-expression][sexp] types in a Lisp-like style. Fusion source code _is_ Ion data. When a data element isn't an S-expression or symbol, it evaluates to itself!
+
+**More Examples:**
+```bash
+# Boolean logic
+fusion eval '(and true false)'                    # false
+fusion eval '(or true false)'                     # true
+
+# List operations
+fusion eval '(head [1, 2, 3, 4])'                # 1
+fusion eval '(tail [1, 2, 3, 4])'                # [2,3,4]
+
+# Conditional expressions
+fusion eval '(if (> 5 3) "yes" "no")'            # "yes"
+```
+
+## Working with Data
+
+Fusion excels at data manipulation. Let's explore various data types and operations:
+
+### Numbers and Math
+```bash
+# Basic arithmetic
+fusion eval '(+ 10 20 30)'                       # 60
+fusion eval '(* 2 3 4)'                          # 24
+fusion eval '(/ 100 4)'                          # 25
+
+# Comparison
+fusion eval '(< 5 10)'                           # true
+fusion eval '(== 42 42)'                        # true
+```
+
+### Strings
+```bash
+# String length (requires string module)
+fusion require '/fusion/string' ';' eval '(string_length "hello")'     # 5
+
+# String concatenation
+fusion eval '(string_append "Hello" ", " "World!")'                    # "Hello, World!"
+```
+
+### Lists and Collections
+```bash
+# List creation and access
+fusion eval '[1, 2, 3, (+ 2 2), 5]'             # [1,2,3,4,5]
+fusion eval '(head [10, 20, 30])'               # 10
+fusion eval '(tail [10, 20, 30])'               # [20,30]
+
+# List processing (requires list module)
+fusion require '/fusion/list' ';' eval '(map (lambda (x) (* x 2)) [1, 2, 3])'  # [2,4,6]
+```
+
+### Structures (Objects)
+```bash
+# Structure creation
+fusion eval '{ name: "Alice", age: 30, city: "Seattle" }'
+
+# Field access
+fusion eval '(define person { name: "Bob", age: 25 }) (. person "name")'        # "Bob"
+
+# Nested structures
+fusion eval '{ user: { name: "Charlie", profile: { active: true } } }'
+```
+
+## Script Execution
+
+The `load` command lets you execute Fusion scripts from files. This is perfect for larger programs and reusable code.
+
+### Your First Script
+
+Create a file called `hello.fusion`:
+```fusion
+// Simple greeting function
+(define (greet name)
+  (string_append "Hello, " name "!"))
+
+// Call the function
+(greet "World")
+```
+
+Run it:
+```bash
+fusion load hello.fusion
+```
+**Output:** `"Hello, World!"`
+
+### Processing Input
+
+Scripts can read from standard input. Create `double.fusion`:
+```fusion
+// Read a number from input and double it
+(define input (read))
+(define result (* input 2))
+(writeln "Input: " input ", Double: " result)
+result
+```
+
+Use it:
+```bash
+echo "21" | fusion load double.fusion
+```
+**Output:** 
+```
+Input: 21, Double: 42
+42
+```
+
+### Real-World Example: Git Author Analysis
+
+Let's create a practical script that processes Git log data. Create `authors.fusion`:
+
+```fusion
+(define all_names
+  '''
+A sexp (linked list) containing all the values on the
+current input stream.
+  '''
+  (series_to_sexp (in_port)))
+
+(define (deduplicate s)
+  '''
+Remove duplicate values from sexp `s`, keeping the _last_
+copy of any duplicates.
+  '''
+  (if (is_empty s) s
+    // Decompose the sexp into its head/tail (aka car/cdr).
+    (let [(name   (head s)),
+          (others (tail s))]
+      (if (any (|n| (== n name)) others)
+        // The name is in the tail, so ignore this copy.
+        (deduplicate others)
+        // The name is not in the tail, so keep it and
+        // dedup the tail.
+        (pair name (deduplicate others))))))
+
+// Print the deduplicated names in chrono order, one per line.
+(for [(name (reverse (deduplicate all_names)))]
+  (displayln name))
+```
+
+Run the script over Git log output:
+```bash
+git log --pretty=format:'"%an"' | fusion load authors.fusion
+```
+
+You'll see deduplicated author names in chronological order of their first commit. This demonstrates Fusion's power for ad-hoc data processing.
+
+## Interactive Development
+
+The `repl` command starts an interactive Read-Eval-Print Loop, perfect for experimentation and learning.
+
+### Starting the REPL
+```bash
+fusion repl
+```
+
+You'll see:
+```
+Welcome to Fusion!
+
+Type...
+  (exit)            to exit
+  (help SOMETHING)  to see documentation; try '(help help)'!
+
+$ 
+```
+
+### REPL Features
+
+**Define and use variables:**
+```fusion
+$ (define x 42)
+$ (define y 8)
+$ (+ x y)
+50
+```
+
+**Create functions:**
+```fusion
+$ (define (factorial n)
+    (if (<= n 1) 
+        1 
+        (* n (factorial (- n 1)))))
+$ (factorial 5)
+120
+```
+
+**Get help:**
+```fusion
+$ (help +)          ; Help for addition function
+$ (help help)       ; Help for the help system
+```
+
+**Work with data:**
+```fusion
+$ (define data { users: [{ name: "Alice", age: 30 }, { name: "Bob", age: 25 }] })
+$ (. data "users")
+[{name:"Alice",age:30},{name:"Bob",age:25}]
+```
+
+**Exit the REPL:**
+```fusion
+$ (exit)
+Goodbye!
+```
+
+## Module System
+
+Fusion has a rich module system. Use `require` to import functionality:
+
+### Standard Library Modules
+
+**String operations:**
+```bash
+fusion require '/fusion/string' ';' repl
+```
+```fusion
+$ (string_length "hello world")
+11
+$ (string_split "a,b,c" ",")
+["a","b","c"]
+$ (string_upper "hello")
+"HELLO"
+```
+
+**List processing:**
+```bash
+fusion require '/fusion/list' ';' repl
+```
+```fusion
+$ (map (lambda (x) (* x x)) [1, 2, 3, 4])
+[1,4,9,16]
+$ (filter (lambda (x) (> x 5)) [1, 3, 7, 2, 9, 4])
+[7,9]
+$ (fold + 0 [1, 2, 3, 4, 5])
+15
+```
+
+**I/O operations:**
+```bash
+fusion require '/fusion/io' ';' repl
+```
+```fusion
+$ (writeln "Hello, " "World!")
+Hello, World!
+$ (display "No newline")
+No newline
+```
+
+### Module Discovery
+
+Explore available modules:
+```bash
+fusion require '/fusion' ';' repl
+```
+```fusion
+$ (help)           ; General help
+$ (help map)       ; Help for map function
+$ (help string_length)  ; Help for string functions
+```
+
+## Command Chaining
+
+Chain multiple commands with `;` to build complex workflows:
+
+### Basic Chaining
+```bash
+# Import module, then use it
+fusion require '/fusion/string' ';' eval '(string_length "test")'
+```
+
+### Multi-step Processing
+```bash
+# Define data, process it, show result
+fusion eval '(define nums [1, 2, 3, 4, 5])' ';' \
+       require '/fusion/list' ';' \
+       eval '(map (lambda (x) (* x x)) nums)'
+```
+
+### Setup and Interactive Session
+```bash
+# Load modules and start REPL
+fusion require '/fusion/string' ';' \
+       require '/fusion/list' ';' \
+       eval '(define greeting "Welcome to Fusion!")' ';' \
+       repl
+```
+
+## Data Processing Workflows
+
+### JSON-like Data Processing
+```bash
+# Process structured data
+echo '{"users": [{"name": "Alice", "score": 85}, {"name": "Bob", "score": 92}]}' | \
+fusion eval '(define data (read))' ';' \
+       eval '(define users (. data "users"))' ';' \
+       require '/fusion/list' ';' \
+       eval '(map (lambda (user) (. user "score")) users)'
+```
+
+### File Processing
+```bash
+# Create sample data
+echo '[1, 2, 3, 4, 5]' > numbers.ion
+
+# Process the file
+fusion eval '(define data (with_ion_from_file "numbers.ion" read))' ';' \
+       require '/fusion/list' ';' \
+       eval '(fold + 0 data)'
+```
+
+### Streaming Data
+```bash
+# Generate data and process it
+seq 1 10 | fusion eval '(for [(n (in_port))] (writeln "Number: " n " Square: " (* n n)))'
+```
+
+## Advanced Features
+
+### Coverage Reports
+```bash
+# Run tests with coverage
+fusion --repositories ./modules load test-suite.fusion
+
+# Generate coverage report
+fusion report_coverage ./coverage-data ./coverage-report
+```
+
+### Custom Repositories
+```bash
+# Use custom module repositories
+fusion --repositories /path/to/my/modules:/path/to/shared/modules \
+       require '/myproject/utils' ';' \
+       load main.fusion
+```
+
+### Ion Catalogs
+```bash
+# Use shared symbol tables for efficient data processing
+fusion --catalogs ./catalogs:/usr/share/ion-catalogs \
+       load data-processor.fusion < large-dataset.ion
+```
 
 
 ## What's Next?
 
-With these basic examples at hand, we recommend browsing the
-[Ion Fusion Language Reference](fusion.html) to learn more about the operators used in the 
-preceding examples.
+Congratulations! You've learned the fundamentals of the Fusion CLI. Here are your next steps:
+
+### Explore the Documentation
+- **[CLI Reference](cli_reference.html)** - Complete command reference with all options
+- **[Language Reference](fusion.html)** - Comprehensive guide to Fusion language features
+- **[CLI Quick Start](cli_quickstart.html)** - Quick reference for common tasks
+
+### Practice with Examples
+- **Data Processing:** Try processing CSV, JSON, or Ion data files
+- **Scripting:** Create utility scripts for common tasks
+- **Interactive Development:** Use the REPL to explore the standard library
+
+### Advanced Topics
+- **Module Development:** Create your own Fusion modules
+- **Java Integration:** Embed Fusion in Java applications
+- **Performance Optimization:** Learn about efficient data processing patterns
+
+### Get Help
+- **Built-in Help:** Use `fusion help` and the REPL's `(help)` system
+- **Community:** Join our [Slack workspace](https://join.slack.com/t/ion-fusion/shared_invite/zt-2y0jr8vh2-bZLa66hdyZ3ykHcgOcYkcA)
+- **Issues:** Report bugs or request features on [GitHub](https://github.com/ion-fusion/fusion-java/issues)
+
+### Real-World Applications
+Consider using Fusion for:
+- **Data ETL pipelines**
+- **Configuration processing**
+- **Log analysis and reporting**
+- **API data transformation**
+- **Build and deployment scripts**
 
-[About the `fusion` CLI](about_cli.html) explains the interface in more detail.
+Happy coding with Ion Fusion!
 
 
-[Amazon Corretto]: https://aws.amazon.com/corretto
+[Corretto]: https://aws.amazon.com/corretto
 [CONTRIBUTORS]: https://github.com/ion-fusion/fusion-java/blob/main/CONTRIBUTORS.md
 [SDK]:          https://github.com/ion-fusion/fusion-java/releases
 [sexp]:   https://amazon-ion.github.io/ion-docs/docs/spec.html#sexp