syntaxis/docs/installation-guide.md

# Installation Guide

Complete guide to installing syntaxis binaries, configurations, and wrappers.

## Quick Start

Install all binaries with one command:

```bash
just scripts-install all
```

This command:
1. Compiles all binaries (workspace, syntaxis-tui, syntaxis-dashboard)
2. Installs them to `~/.cargo/bin/`
3. Deploys configuration files to `~/.config/core/`
4. Creates intelligent wrapper scripts that auto-discover configurations
5. Registers installation details in `.syntaxis/manifest.toml`

## Installation Commands

### Install All Binaries
```bash
just scripts-install all
```
Installs workspace, syntaxis-tui, and syntaxis-dashboard with configurations.

### Install Specific Binary
```bash
just scripts-install workspace          # Install CLI only
just scripts-install syntaxis-tui      # Install TUI only
just scripts-install syntaxis-dashboard # Install web dashboard
```

### Keep Build Artifacts
```bash
just scripts-install all --keep-target
```
By default, build artifacts are removed to save disk space. Use `--keep-target` to keep them.

### Check Installation Status
```bash
just scripts-install status
```
Shows which binaries are installed and their locations.

### List Available Binaries
```bash
just scripts-install list
```
Lists all available binaries with descriptions.

## What Gets Installed

### Binaries
| Binary | Type | Location | Purpose |
|--------|------|----------|---------|
| `workspace` | CLI | `~/.cargo/bin/workspace` | Project management command-line tool |
| `syntaxis-tui` | TUI | `~/.cargo/bin/syntaxis-tui` | Interactive terminal user interface |
| `syntaxis-dashboard` | Web | `~/.cargo/bin/syntaxis-dashboard` | Web-based dashboard (Leptos, port 3000) |

### Configuration Files
Location: `~/.config/core/`

| File | Purpose |
|------|---------|
| `syntaxis-api.toml` | Main configuration for workspace ecosystem |
| `features/auth.toml` | Authentication configuration |
| `features/cache.toml` | Caching configuration |
| `features/database.toml` | Database configuration |
| `features/health.toml` | Health check configuration |
| `features/metrics.toml` | Metrics collection configuration |
| `features/multi_tenant.toml` | Multi-tenancy configuration |
| `features/rate_limit.toml` | Rate limiting configuration |
| `features/projects.toml` | Project management settings |
| `features/tasks.toml` | Task tracking settings |
| `features/phases.toml` | Phase lifecycle settings |
| `features/audit.toml` | Audit trail configuration |

### Data Directories
| Directory | Purpose |
|-----------|---------|
| `~/.local/share/core/` | Runtime data and databases |
| `.syntaxis/` | Local installation tracking manifest |

## How Wrapper Scripts Work

After installation, wrapper scripts in `~/.cargo/bin/` automatically:

1. **Search for configuration files** in this priority order:
   - `~/.config/core/{binary}.toml`
   - `~/.config/core/syntaxis-api.toml`
   - `.project/{binary}.toml` (project-specific)
   - `.vapora/{binary}.toml` (VAPORA-specific)

2. **Set environment variables**:
   - `WORKSPACE_CONFIG_PATH` - Found configuration file
   - `WORKSPACE_CONFIG_DIR` - Configuration directory
   - `WORKSPACE_DATA_DIR` - Runtime data directory

3. **Create data directory** if needed
4. **Execute the actual binary** with all arguments passed through

### Example: Running workspace CLI
```bash
$ workspace --help
# Wrapper script automatically:
# 1. Finds ~/.config/core/workspace.toml
# 2. Sets WORKSPACE_CONFIG_PATH
# 3. Executes ~/.cargo/bin/workspace.real --help
```

## Installation Structure

### Before Installation
```
~/.cargo/bin/
  (other cargo binaries)
```

### After Installation
```
~/.cargo/bin/
  workspace              (wrapper script)
  workspace.real         (actual binary)
  syntaxis-tui          (wrapper script)
  syntaxis-tui.real     (actual binary)
  syntaxis-dashboard    (actual binary)
  (other cargo binaries)

~/.config/core/
  syntaxis-api.toml     (main config)
  features/
    auth.toml
    cache.toml
    database.toml
    health.toml
    metrics.toml
    multi_tenant.toml
    rate_limit.toml
    projects.toml
    tasks.toml
    phases.toml
    audit.toml

~/.local/share/core/
  (runtime data)

.syntaxis/
  manifest.toml          (installation tracking)
```

## Installation Manifest

After installation, `.syntaxis/manifest.toml` tracks:

```toml
[installation]
created_at = "2025-11-15 12:34:56"
last_updated = "2025-11-15 12:34:56"
installation_root = "/path/to/syntaxis"
ecosystem_version = "0.1.0"

[binaries.workspace]
installed = true
wrapper = true
path = "~/.cargo/bin/workspace"
real_binary = "~/.cargo/bin/workspace.real"
version = "0.1.0"
installed_at = "2025-11-15 12:34:56"

[configurations]
config_dir = "~/.config/syntaxis"
deployed_count = 11

[configurations.syntaxis-api]
deployed = true
path = "~/.config/core/syntaxis-api.toml"
checksum = "sha256:..."
deployed_at = "2025-11-15 12:34:56"

[verification]
all_binaries_present = true
all_configs_deployed = true
wrappers_created = true
environment_variables_set = true
```

This manifest enables:
- **Version tracking** - Know when each component was installed
- **Integrity verification** - Check config file integrity via checksums
- **Installation status** - Verify all components are properly deployed
- **Rollback capability** - Reference for reverting to previous versions

## Troubleshooting

### Binary not found
```bash
# Ensure ~/.cargo/bin is in PATH
echo $PATH | grep ".cargo/bin"

# If not found, add to shell profile:
export PATH="$HOME/.cargo/bin:$PATH"
```

### Config files not loading
```bash
# Check if wrapper script is finding config
workspace --help  # Should show config path in output

# Verify config directory exists
ls -la ~/.config/core/
```

### Reinstalling
To reinstall with fresh configurations:
```bash
# Remove old installation
rm -rf ~/.config/syntaxis
rm ~/.cargo/bin/workspace*
rm ~/.cargo/bin/syntaxis-tui*

# Reinstall
just scripts-install all
```

## Next Steps

1. **Check installation status**:
   ```bash
   just scripts-install status
   ```

2. **Read configuration guide**:
   ```bash
   cat docs/configuration.md
   ```

3. **Use the CLI**:
   ```bash
   workspace --help
   workspace project list
   ```

4. **Launch the TUI**:
   ```bash
   syntaxis-tui
   ```

5. **Start the web dashboard**:
   ```bash
   syntaxis-dashboard  # Runs on http://localhost:3000
   ```

## Support

- **Bug reports**: See `.coder/` directory for issue tracking
- **Configuration help**: See `docs/configuration.md`
- **Technical details**: See `WRAPPER_DESIGN.md`