syntaxis/docs/installation-quickstart.md

Installation Quick Reference

One-Command Installation

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)

source ~/.bashrc     # or ~/.zshrc, ~/.config/fish/config.fish

2. Verify installation

workspace --help
syntaxis-tui --version
which syntaxis-dashboard

3. Check configuration

ls -la ~/.config/core/

4. Start using

# 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:

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:

# 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:

# Visit https://rustup.rs/ for detailed instructions
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

---

Installation Options

Standard (Default)

curl -sSL https://raw.githubusercontent.com/.../install.sh | bash

Installs everything with prompts.

Unattended (No prompts)

bash install.sh --unattended

Perfect for scripts and CI/CD.

Custom install location

bash install.sh --prefix /opt/workspace

Install to custom directory instead of home.

Configuration only

bash install.sh --config-only

Deploy configuration files (binaries already installed).

Dry run (preview without changes)

bash install.sh --dry-run

See what would be installed without making changes.

Full help

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:

# 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 - Technical deep-dive with 12 levels of explanation
• BOOTSTRAP_DIAGRAMS.md - Visual diagrams and flowcharts
• docs/installation-guide.md - Step-by-step setup guide
• docs/configuration.md - Configuration reference

---

Common Tasks After Installation

Initialize a new project

workspace create-project --name my-project

Start the TUI (Terminal UI)

syntaxis-tui

Start the Web Dashboard

syntaxis-dashboard
# Open http://localhost:3000 in browser

Run CLI commands

workspace --help
workspace list-projects
workspace list-tasks --project my-project

Check configuration

cat ~/.config/core/syntaxis-api.toml

Uninstall

# 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.