syntaxis/docs/install.md

# Installation Guide

Complete reference for extracting and installing SYNTAXIS from the bundle.

## Overview

This guide covers:
1. **Quick overview** (3 steps)
2. **Prerequisites** (system requirements)
3. **Installation methods** (automatic, manual, NuShell)
4. **Verification** (checking successful installation)
5. **Troubleshooting** (common issues)

## 🚀 Quick Start (4 Steps)

```bash
# Step 1: Extract bundle
tar -xzf syntaxis-v0.1.0-*.tar.gz
cd syntaxis-v0.1.0-*

# Step 2: Install binaries
bash install.sh --interactive

# Step 3: Configure settings
bash setup-config.sh --interactive

# Step 4: Verify
syntaxis-cli --version
```

---

## Prerequisites

### System Requirements

- **Memory**: 512 MB minimum (1 GB recommended for full stack)
- **Disk Space**: 100 MB for binaries + data
- **Network**: Optional (offline operation supported)

### Supported Platforms

| Platform | Architecture | Status |
|----------|--------------|--------|
| Linux (glibc) | x86_64, ARM64 | ✅ Tested |
| macOS | Intel (x86_64), Apple Silicon (ARM64) | ✅ Tested |
| Windows | x86_64 (MSVC) | ✅ Tested |

### Required Tools

The bundle is **self-contained**—no additional tools required!

Optional tools (for advanced setup):
- `bash` or `zsh` (for `install.sh`) - available on all systems
- `nu` (for `install.nu`) - [install NuShell](https://www.nushell.sh)

---

## Installation Methods

### Recommended: Two-Step Installation

The cleanest approach: separate install and config steps.

**Step 1: Install binaries**
```bash
# Interactive (prompts for options)
bash install.sh --interactive

# Unattended (uses defaults)
bash install.sh --prefix ~/.local

# Verify before installing
bash install.sh --prefix ~/.local --dry-run

# Custom prefix
bash install.sh --prefix /opt/syntaxis
```

**Step 2: Configure**
```bash
bash setup-config.sh --interactive
```

### Alternative: NuShell Installer

For NuShell users who prefer the alternative:

```bash
# Make sure NuShell is installed first
# See: https://www.nushell.sh/book/installation.html

# Step 1: Install using NuShell
nu install.nu --prefix ~/.local

# Step 2: Configure
bash setup-config.sh --interactive
```

### Advanced: Manual Installation

For maximum control and custom setups:

```bash
# Create installation directory
mkdir -p ~/.local/bin

# Copy binaries
cp bin/* ~/.local/bin/

# Make executable
chmod +x ~/.local/bin/syntaxis-*

# Create config directory
mkdir -p ~/.config/syntaxis

# Copy configs
cp configs/*.toml ~/.config/syntaxis/

# Create data directory
mkdir -p ~/.local/share/syntaxis

# Update PATH (one-time)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

---

## Step-by-Step Installation

### 1. Extract Bundle

```bash
# Using tar (Linux, macOS)
tar -xzf syntaxis-v0.1.0-*.tar.gz
cd syntaxis-v0.1.0-*

# Using unzip (Windows, macOS)
unzip syntaxis-v0.1.0-*.zip
cd syntaxis-v0.1.0-*
```

### 2. Install Binaries

```bash
bash install.sh --interactive
```

This installs the binaries and updates your PATH automatically.

### 3. Configure Settings

```bash
bash setup-config.sh --interactive
```

This creates configuration files and prompts for customization.

### 4. Configure Shell

After installation, update your shell configuration to add syntaxis to PATH:

**For bash/zsh:**
```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**For fish:**
```bash
set -Ua fish_user_paths ~/.local/bin
```

**For NuShell:**
```bash
export PATH="($env.HOME)/.local/bin:($env.PATH)"
```

### 5. Verify Installation

```bash
# Check all binaries
syntaxis-cli --version
syntaxis-tui --version
syntaxis-api --version

# Should show: syntaxis-* v0.1.0

# List configuration
ls ~/.config/syntaxis/
```

---

## NuShell: Full-Featured Wrappers (Optional)

### What is NuShell?

NuShell is a modern shell that provides advanced features for SYNTAXIS wrappers:
- Better config discovery with multiple fallback paths
- Advanced environment variable handling
- Full-featured configuration injection

### Do I Need NuShell?

**Short Answer**: No, SYNTAXIS works without it.

**With NuShell** (Recommended):
- ✅ Full-featured wrappers
- ✅ Advanced config discovery
- ✅ Best user experience

**Without NuShell** (Still Works):
- ✅ Simplified auto-config (basic paths only)
- ✅ Still auto-injects config path
- ✅ Good enough for most users

### Installing NuShell

The installer will detect if NuShell is installed and prompt you with options:

```
⚠️  NuShell Not Detected
Continue with simplified wrappers? [Y/n/i]
  Y = Yes, continue (recommended)
  N = No, let me install NuShell first
  i = Show installation guide
```

**Installation Instructions** (by OS):

**macOS (Homebrew)**:
```bash
brew install nushell
```

**macOS (Cargo)**:
```bash
cargo install nu
```

**Linux (Arch)**:
```bash
pacman -S nushell
```

**Linux (Ubuntu/Debian)**:
```bash
cargo install nu
```

**Linux (Fedora)**:
```bash
dnf install nushell
```

**Windows (WinGet)**:
```bash
winget install nushell
```

**Windows (Cargo)**:
```bash
cargo install nu
```

### Using Wrappers Without NuShell

If you choose to continue without NuShell:
- Wrappers still auto-discover and inject config paths
- Basic config discovery works (~6 paths searched)
- Command execution is normal and transparent

To upgrade later, simply install NuShell:
```bash
# Install NuShell (see above for your OS)
# Then re-run the installer
./install.sh
```

---

## Environment Setup

### Essential Environment Variables

Set these in your shell rc file:

```bash
# Configuration directory
export SYNTAXIS_CONFIG_DIR="$HOME/.config/syntaxis"

# Data directory
export SYNTAXIS_DATA_DIR="$HOME/.local/share/syntaxis"

# Database backend (optional)
export SYNTAXIS_DATABASE="default"  # or "surrealdb"
```

### Optional Configuration

```bash
# Logging level
export RUST_LOG="info"  # debug, info, warn, error

# API server settings
export SYNTAXIS_API_PORT=3000
export SYNTAXIS_API_HOST=127.0.0.1
```

---

## Post-Installation Configuration

### Interactive Configuration

```bash
# Run interactive configuration (done in step 3)
bash setup-config.sh --interactive
```

### Manual Configuration

Default configs are created automatically. Customize them:

```bash
# Edit CLI configuration
nano ~/.config/syntaxis/syntaxis-cli.toml

# Edit TUI configuration
nano ~/.config/syntaxis/syntaxis-tui.toml

# Edit API configuration
nano ~/.config/syntaxis/syntaxis-api.toml
```

See [CONFIG.md](CONFIG.md) for all configuration options.

---

## Bundle Contents Reference

```
syntaxis-v0.1.0-<target>/
├── Binaries (ready to run)
│   └── bin/
│       ├── syntaxis-cli       # Command-line interface
│       ├── syntaxis-tui       # Terminal user interface
│       └── syntaxis-api       # REST API server
│
├── Installation Scripts
│   ├── install.sh             # Bash installer (Step 1: Install binaries)
│   ├── install.nu             # NuShell installer (alternative)
│   └── setup-config.sh        # Configuration helper (Step 2: Configure)
│
├── Configurations
│   └── configs/
│       ├── database-default.toml     # SQLite settings
│       ├── database-surrealdb.toml   # SurrealDB settings
│       ├── syntaxis-cli.toml         # CLI config
│       ├── syntaxis-tui.toml         # TUI config
│       └── syntaxis-api.toml         # API config
│
├── Documentation
│   ├── README.md               # Overview (this directory)
│   ├── QUICK_START.md          # 5-minute tutorial
│   ├── docs/installation.md              # Installation (this file)
│   ├── CONFIG.md               # Configuration reference
│   └── TROUBLESHOOTING.md      # Common issues
│
└── Metadata
    ├── manifest.toml           # Bundle inventory
    └── .checksums.toml         # SHA256 checksums
```

---

## Verification

### Verify Binaries

```bash
# Check all binaries are executable
which syntaxis-cli
which syntaxis-tui
which syntaxis-api

# Test basic commands
syntaxis-cli --help
syntaxis-cli --version
```

### Verify Configuration

```bash
# Check config directory
ls -la ~/.config/syntaxis/

# Validate TOML files
cat ~/.config/syntaxis/syntaxis-cli.toml | head -10
```

### Verify Data Directory

```bash
# Check data directory exists
ls -la ~/.local/share/syntaxis/

# Create sample database
syntaxis-cli project list
```

---

## Troubleshooting Installation

### "Command not found"

```bash
# Check if in PATH
echo $PATH | grep .local/bin

# Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### "Permission denied"

```bash
# Make binaries executable
chmod +x ~/.local/bin/syntaxis-*

# Verify permissions
ls -l ~/.local/bin/syntaxis-*
```

### Installer script fails

```bash
# Run with verbose output
bash install.sh --verbose --prefix ~/.local

# Check if directories exist
mkdir -p ~/.local/bin
mkdir -p ~/.config/syntaxis
mkdir -p ~/.local/share/syntaxis
```

### Configuration not found

```bash
# Create missing directory
mkdir -p ~/.config/syntaxis

# Run setup script
bash setup-config.sh

# Copy from bundle
cp configs/*.toml ~/.config/syntaxis/
```

See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for more help.

---

## Uninstallation

To remove SYNTAXIS:

```bash
# Remove binaries
rm ~/.local/bin/syntaxis-*

# Remove configuration (optional)
rm -rf ~/.config/syntaxis/

# Remove data (optional)
rm -rf ~/.local/share/syntaxis/

# Clean up PATH (edit ~/.bashrc or equivalent)
# Remove the SYNTAXIS-related export statement
```

---

## Next Steps

1. **Quick Start**: Read [QUICK_START.md](QUICK_START.md) (5 minutes)
2. **Configure**: Read [CONFIG.md](CONFIG.md) for all options
3. **Create Project**: Use `syntaxis-cli` or `syntaxis-tui`
4. **Run API**: Start server with `syntaxis-api`

---

## Getting Help

- **Local Issues**: Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- **Configuration**: See [CONFIG.md](CONFIG.md)
- **Quick Examples**: See [QUICK_START.md](QUICK_START.md)
- **Online Help**: https://doc.syntaxis.dev
- **Report Issues**: https://github.com/syntaxis/syntaxis/issues

---

**SYNTAXIS** v0.1.0 • [syntaxis.dev](https://syntaxis.dev)