syntaxis/docs/installation-quickstart.md

# Installation Quick Reference

## One-Command Installation

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

Done! Everything is installed and ready to use.

---

## What Gets Installed

| Component | Source | Method | Time |
|-----------|--------|--------|------|
| Rust toolchain | https://sh.rustup.rs | Pre-compiled bootstrap | 30-60s |
| NuShell | crates.io | Compiled from Rust source | 1-2 min |
| Just | crates.io | Compiled from Rust source | 1-2 min |
| workspace binaries | This repo | Compiled from Rust source | 5-10 min |
| Configuration | This repo | Copied to ~/.config/ | <1 min |

**Total installation time:** 15-30 minutes (mostly network + compilation)

---

## The Bootstrap Architecture (Simple Explanation)

```
1. You run: curl ... | bash
   ↓
2. Install script downloads pre-compiled Rust (100MB)
   ↓
3. Rust can now compile source code
   ↓
4. Rust compiles NuShell, Just, and our workspace binaries
   ↓
5. Everything works! ✅
```

**Key insight:** We don't pre-compile NuShell or workspace binaries in the repository. Instead, we let Rust (which we just installed) compile them from source. This keeps the repository small (~500MB) while still enabling one-command installation.

---

## Installation Locations

| What | Where | Why |
|------|-------|-----|
| Rust | `~/.rustup/` | Managed by rustup |
| Cargo packages | `~/.cargo/bin/` | Standard cargo location |
| workspace binaries | `~/.cargo/bin/` | From `cargo install` |
| Configuration | `~/.config/core/` | XDG Base Directory spec |
| Data files | `~/.local/share/core/` | XDG Base Directory spec |
| Logs | `~/.local/state/core/` | XDG Base Directory spec |

---

## First-Time Setup After Installation

### 1. Reload shell (to update PATH)
```bash
source ~/.bashrc     # or ~/.zshrc, ~/.config/fish/config.fish
```

### 2. Verify installation
```bash
workspace --help
syntaxis-tui --version
which syntaxis-dashboard
```

### 3. Check configuration
```bash
ls -la ~/.config/core/
```

### 4. Start using
```bash
# CLI
workspace create-project --name my-project

# TUI
syntaxis-tui

# Dashboard (web UI)
syntaxis-dashboard
```

---

## Architecture Detection (Automatic)

The installer automatically detects your system and downloads the correct pre-compiled Rust:

| Your System | Detection | Rust Version Downloaded |
|-------------|-----------|------------------------|
| M1/M2/M3 Mac | `uname -m` = arm64 | rust-*-aarch64-apple-darwin |
| Intel Mac | `uname -m` = x86_64 | rust-*-x86_64-apple-darwin |
| Linux ARM 64-bit | `uname -m` = aarch64 | rust-*-aarch64-unknown-linux-gnu |
| Linux Intel 64-bit | `uname -m` = x86_64 | rust-*-x86_64-unknown-linux-gnu |
| Windows | `uname -s` = MINGW64 | rust-*-x86_64-pc-windows-gnu |

You don't need to specify anything - it's all automatic!

---

## Troubleshooting Installation

### Problem: Installation takes too long
**Cause:** Compilation on slow machine or network
**Solution:** Installation is 5-10 minutes for compilation + 30-60 seconds for downloads
- On first install: Complete rebuild (slower)
- On subsequent installs: Incremental (faster)

### Problem: "command not found: workspace"
**Cause:** Shell didn't reload PATH
**Solution:**
```bash
source ~/.bashrc  # or ~/.zshrc
which workspace   # should show ~/.cargo/bin/workspace
```

### Problem: "curl: command not found"
**Cause:** System doesn't have curl installed
**Solution:** Install curl first:
```bash
# macOS
brew install curl

# Ubuntu/Debian
sudo apt-get install curl

# Fedora/CentOS
sudo yum install curl
```

### Problem: Rust installation fails
**Cause:** Network issue or unsupported architecture
**Solution:** Install Rust manually:
```bash
# Visit https://rustup.rs/ for detailed instructions
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

---

## Installation Options

### Standard (Default)
```bash
curl -sSL https://raw.githubusercontent.com/.../install.sh | bash
```
Installs everything with prompts.

### Unattended (No prompts)
```bash
bash install.sh --unattended
```
Perfect for scripts and CI/CD.

### Custom install location
```bash
bash install.sh --prefix /opt/workspace
```
Install to custom directory instead of home.

### Configuration only
```bash
bash install.sh --config-only
```
Deploy configuration files (binaries already installed).

### Dry run (preview without changes)
```bash
bash install.sh --dry-run
```
See what would be installed without making changes.

### Full help
```bash
bash install.sh --help
```
See all available options.

---

## System Requirements

### Before Installation
You only need these (on every system):
- `bash` shell (for running installer)
- `curl` (for downloading files)
- `tar` & `gzip` (for extracting archives)
- `uname` (for detecting system)
- `git` (for cloning repository)

### After Installation
You'll have:
- Rust 1.91+ (with cargo, rustfmt, clippy)
- NuShell 0.90+
- Just 1.30+
- workspace binaries (CLI, TUI, Dashboard)

---

## How Bootstrap Compiler Works (Detail)

### The Problem
Rust is written in Rust. To compile Rust, you need Rust. Circular dependency!

### The Solution
Rust publishes pre-compiled binaries on https://static.rust-lang.org/dist/

**How our installer uses this:**

```bash
# 1. Download installer script
curl https://sh.rustup.rs

# 2. Script detects your system
uname -s  # Darwin
uname -m  # arm64
# Constructs: aarch64-apple-darwin

# 3. Download pre-compiled Rust for that architecture
# From: https://static.rust-lang.org/dist/
# File: rust-1.91.1-aarch64-apple-darwin.tar.gz (100MB)

# 4. Extract and install to ~/.rustup/

# 5. NOW you have a working rustc!
rustc --version  # rustc 1.91.1
```

### Why Pre-Compiled Only for Rust?

We could pre-compile EVERYTHING, but:
- **Repository would be 5GB+** (instead of 500MB)
- **Updates would take hours** (rebuild all 50+ architectures)
- **Maintenance nightmare** (new Rust version every week)

Instead, we:
- Pre-compile ONLY rustc (the minimal dependency)
- Use rustc to compile everything else from source
- Keep repository small
- Get automatic updates when you reinstall

---

## Why This Architecture Is Elegant

```
                    BOOTSTRAP COMPILER
                          ↓
    ONE pre-compiled binary (rustc)
                          ↓
        Can compile ANYTHING from source
                          ↓
        ┌───────────────┬─────────────┬──────────────┐
        ↓               ↓             ↓              ↓
    NuShell          Just      workspace        Others
    (1-2 min)    (1-2 min)    (5-10 min)
                          ↓
                    Everything ready!
```

This is why:
- Installation is fast (not 4+ hours)
- We don't need 5GB repository
- Works on any of 50+ architectures
- Automatic updates (Rust updates → new binaries available)

---

## For More Details

- **[BOOTSTRAP_EXPLAINED.md](./BOOTSTRAP_EXPLAINED.md)** - Technical deep-dive with 12 levels of explanation
- **[BOOTSTRAP_DIAGRAMS.md](./BOOTSTRAP_DIAGRAMS.md)** - Visual diagrams and flowcharts
- **[docs/installation-guide.md](./docs/installation-guide.md)** - Step-by-step setup guide
- **[docs/configuration.md](./docs/configuration.md)** - Configuration reference

---

## Common Tasks After Installation

### Initialize a new project
```bash
workspace create-project --name my-project
```

### Start the TUI (Terminal UI)
```bash
syntaxis-tui
```

### Start the Web Dashboard
```bash
syntaxis-dashboard
# Open http://localhost:3000 in browser
```

### Run CLI commands
```bash
workspace --help
workspace list-projects
workspace list-tasks --project my-project
```

### Check configuration
```bash
cat ~/.config/core/syntaxis-api.toml
```

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

# Remove configuration
rm -rf ~/.config/core/

# Remove Rust (if you only installed it for workspace)
rustup self uninstall
```

---

**Installation should be simple. If it's not, something went wrong. Check the troubleshooting section or open an issue.**