```
╔═════════════════════════════════╗
║  ┏━┓ ╻ ╻ ┏┓╻ ╺┳╸ ┏━┓ ╻ ╻ ╻ ┏━┓  ║
║  ┗━┓ ┗┳┛ ┃┗┫  ┃  ┣━┫ ┏╋┛ ┃ ┗━┓  ║
║  ┗━┛  ╹  ╹ ╹  ╹  ╹ ╹ ╹ ╹ ╹ ┗━┛  ║
║   ▲ Systematic Orchestration    ║
║   ■  Perfectly Arranged         ║
║          syntaxis.dev           ║
╚═════════════════════════════════╝
```

# Installation Guide

Complete guide for installing syntaxis on any system.

## Quick Install (Recommended)

The one-liner installer handles everything:

```bash
curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash
```

**Installation time:** 15-30 minutes (first-time build takes longest)

## What Gets Installed

### Binaries (to ~/.cargo/bin)
- `workspace` - CLI tool for project management
- `syntaxis-tui` - Terminal user interface
- `syntaxis-dashboard` - Web dashboard (runs on localhost:3000)

### Configurations (to ~/.config/core/)
- `syntaxis-api.toml` - Main configuration file
- `features/*.toml` - 11 feature-specific configs:
  - auth.toml (authentication)
  - cache.toml (caching settings)
  - database.toml (database configuration)
  - health.toml (health checks)
  - metrics.toml (monitoring)
  - multi_tenant.toml (multi-tenancy)
  - rate_limit.toml (rate limiting)
  - projects.toml (project management)
  - tasks.toml (task tracking)
  - phases.toml (phase lifecycle)
  - audit.toml (audit trail)

### Data Directories
- `~/.local/share/core/` - Runtime data and databases
- `~/.syntaxis/` - Installation tracking manifest

## Installation Methods

### Method 1: Curl One-Liner (Easiest)

```bash
curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh | bash
```

This is safe because:
1. You can inspect the script first: `curl -sSL ... -o install.sh && cat install.sh`
2. The script logs all operations to `~/.syntaxis/install.log`
3. Failed installations are rolled back automatically

### Method 2: Download First, Then Run

```bash
# Download the installer
curl -sSL https://raw.githubusercontent.com/core/syntaxis/main/install.sh -o install.sh

# Inspect it
less install.sh

# Run it
bash install.sh
```

### Method 3: Clone Repository and Install Manually

For developers or those with specific requirements:

```bash
# Clone the repository
git clone https://github.com/core/syntaxis.git
cd syntaxis

# Run the installer from the repo
bash install.sh

# Or use just commands
just build
just install-cli all
```

## Installation Options

### Unattended Mode (No Prompts)
```bash
bash install.sh --unattended
```
Uses all defaults without asking for confirmation.

### Custom Installation Directory
```bash
bash install.sh --prefix /opt/workspace
```
Installs to a custom location instead of `~/.local/share/core/`.

### Skip Dependency Installation
```bash
bash install.sh --skip-deps
```
Assumes Rust, NuShell, and Just are already installed. Only builds and installs workspace binaries.

### Config Only
```bash
bash install.sh --config-only
```
Only deploys configurations without building binaries. Useful for updating config files.

### Dry Run (Preview)
```bash
bash install.sh --dry-run
```
Shows what would be installed without making any actual changes.

### Keep Build Artifacts
```bash
bash install.sh --keep-build
```
By default, build artifacts are removed to save disk space. Use this flag to keep them.

### Skip Tests
```bash
bash install.sh --no-verify
```
Skips test verification (faster, not recommended for production).

### Help
```bash
bash install.sh --help
```
Shows all available options.

## Supported Platforms

### Operating Systems
- ✅ macOS (Intel and Apple Silicon)
- ✅ Ubuntu/Debian Linux
- ✅ Fedora/RHEL Linux
- ✅ Arch Linux
- ✅ WSL2 (Windows Subsystem for Linux)

### Architectures
- ✅ x86_64 (Intel/AMD)
- ✅ aarch64 (ARM64, Apple Silicon)

### Rust Versions
- ✅ 1.75+ (Current stable recommended)

## Post-Installation

### 1. Reload Your Shell
```bash
# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

# For fish
source ~/.config/fish/config.fish
```

### 2. Verify Installation
```bash
# Test CLI
workspace --help

# Test TUI version
syntaxis-tui --version

# Find dashboard binary
which syntaxis-dashboard

# Check config location
echo $WORKSPACE_CONFIG_DIR
```

### 3. Create Your First Project
```bash
workspace project create my-first-project
```

### 4. Launch the TUI
```bash
syntaxis-tui
```

### 5. Start the Web Dashboard
```bash
cd ~/.local/share/syntaxis
just run-dashboard
```
Dashboard runs on http://localhost:3000

## Customizing Configuration

After installation, configurations are at `~/.config/core/`:

```bash
# Edit main configuration
nano ~/.config/core/syntaxis-api.toml

# Edit specific feature config
nano ~/.config/core/features/database.toml

# Environment variable overrides
export WORKSPACE_SERVER_PORT=8081
export WORKSPACE_LOG_LEVEL=debug
```

See [docs/configuration.md](./docs/configuration.md) for all available options.

## Troubleshooting

### Command Not Found
```bash
# Problem: workspace command not found
# Solution 1: Reload shell
source ~/.bashrc

# Solution 2: Check PATH
echo $PATH | grep .cargo/bin

# Solution 3: Check if binary exists
ls -la ~/.cargo/bin/workspace*
```

### Build Failures
```bash
# Check if Rust is installed
rustc --version

# Update Rust
rustup update

# Clean and retry
cargo clean
bash install.sh
```

### Missing Dependencies
```bash
# For macOS - install Xcode tools
xcode-select --install

# For Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libsqlite3-dev

# For Fedora/RHEL
sudo dnf install -y gcc gcc-c++ make pkg-config sqlite-devel

# For Arch
sudo pacman -S --noconfirm base-devel pkg-config sqlite
```

### Permission Errors
```bash
# Installer should NOT require sudo for user installation
# If you see permission errors, check your home directory permissions
ls -ld ~
chmod u+w ~

# Never run installer with sudo!
bash install.sh  # Correct
sudo bash install.sh  # Wrong!
```

### Clean Reinstall
```bash
# Remove old installation
rm -rf ~/.cargo/bin/workspace*
rm -rf ~/.config/syntaxis
rm -rf ~/.local/share/syntaxis
rm -rf ~/.syntaxis

# Reinstall
bash install.sh
```

## Installation Log

All installation details are logged to:
```bash
~/.syntaxis/install.log
```

Check this file if installation fails:
```bash
tail -100 ~/.syntaxis/install.log
```

## Environment Variables

After installation, these environment variables are set:

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

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

# Optional: Manual overrides
export WORKSPACE_SERVER_PORT=8080
export WORKSPACE_LOG_LEVEL=debug
export WORKSPACE_DATABASE_PATH="/custom/path.db"
```

## Uninstalling

To uninstall syntaxis:

```bash
# Remove binaries
rm ~/.cargo/bin/workspace*

# Remove configurations (optional - keep for reinstall)
rm -rf ~/.config/syntaxis

# Remove data and cache
rm -rf ~/.local/share/syntaxis

# Remove installation tracking
rm -rf ~/.syntaxis
```

The project repository can be left as-is for future reinstalls.

## Development Installation

For contributing to syntaxis:

```bash
# Clone repository
git clone https://github.com/core/syntaxis.git
cd syntaxis

# Install tools
rustup default 1.75
cargo install just

# Build everything
just build

# Run all tests
just test

# Run specific test
cargo test -p syntaxis-core

# Build and run CLI
just run-cli --help

# Build and run TUI
just run-tui

# Build and run dashboard
just run-dashboard
```

See [DEVELOPMENT.md](./DEVELOPMENT.md) in the root for more development details.

## Next Steps

1. **Read the Quick Start Guide**: [docs/installation-guide.md](./docs/installation-guide.md)
2. **Configure Your System**: [docs/configuration.md](./docs/configuration.md)
3. **Understand Wrappers**: [WRAPPER_DESIGN.md](./WRAPPER_DESIGN.md)
4. **Use the CLI**: `workspace --help`
5. **Join the Community**: https://github.com/core/syntaxis

## Getting Help

- **GitHub Issues**: https://github.com/core/syntaxis/issues
- **Documentation**: https://github.com/core/syntaxis
- **Installation Log**: `~/.syntaxis/install.log`

---

**Happy installing! 🚀**