syntaxis/docs/installation/installation-comparison.md

# Installation System: Current vs Proposed

**Quick Reference:** Understanding the improvements to target installation with configs and wrappers

---

## Current System (Status Quo)

### Installation Flow

```
User runs: install-cli.nu all

    ↓

1. COMPILE
   └─ cargo build --release (workspace)

    ↓

2. INSTALL BINARIES
   ├─ cargo install --path syntaxis-cli
   │  └─ Binary → ~/.cargo/bin/workspace
   ├─ cargo install --path syntaxis-tui
   │  └─ Binary → ~/.cargo/bin/syntaxis-tui
   ├─ cargo install --path syntaxis-api
   │  └─ Binary → ~/.cargo/bin/syntaxis-api
   └─ cargo install --path syntaxis-dashboard
      └─ No binary (library)

    ↓

3. CLEANUP (optional)
   └─ Remove target/ directories

    ↓

RESULT: Binaries in ~/.cargo/bin/, everything else user's responsibility
```

### Configuration Management

```
Where configs are:
├── syntaxis/syntaxis-api-config.template.toml   ❌ Still named "syntaxis-api"
└── syntaxis/configs/features/*.toml.template

How binaries find config:
├─ Hardcoded path "configs/default.toml"
├─ Environment variable CONFIG_PATH (if set by user)
└─ No standardized discovery

Where configs end up:
└─ Nowhere! (User must manually copy/manage)

Result:
❌ Configs not deployed
❌ Binaries can't find configs
❌ No installation tracking
```

### User Experience

```
$ just scripts-install
✅ workspace: Installed successfully
✅ syntaxis-tui: Installed successfully
✅ syntaxis-api: Installed successfully

$ workspace --version
❌ Error: Config file not found at configs/default.toml

$ nano syntaxis-api.toml
# Manually edit configuration

$ WORKSPACE_CONFIG_PATH=/home/user/syntaxis-api.toml syntaxis-api
# User must manually set environment variable
```

### Problems with Current System

| Problem | Impact | Severity |
|---------|--------|----------|
| Config templates not deployed | User must manually copy configs | 🔴 Critical |
| Binaries can't find deployed configs | Application fails to start | 🔴 Critical |
| No standard config location | Different users have different setups | 🟠 High |
| No installation tracking | Can't verify what's installed | 🟠 High |
| Config filename wrong (lifecycle) | Confusion about which project | 🟡 Medium |
| No wrapper scripts | No automatic environment setup | 🟡 Medium |
| Manual environment setup | Users forget to set variables | 🟡 Medium |

---

## Proposed System (After Phase 1-4)

### Installation Flow

```
User runs: just scripts-install

    ↓

1. COMPILE
   └─ cargo build --release (workspace)

    ↓

2. INSTALL BINARIES
   ├─ cargo install --path syntaxis-cli
   │  └─ Binary → ~/.cargo/bin/workspace
   ├─ cargo install --path syntaxis-tui
   │  └─ Binary → ~/.cargo/bin/syntaxis-tui
   ├─ cargo install --path syntaxis-api
   │  └─ Binary → ~/.cargo/bin/syntaxis-api
   └─ cargo install --path syntaxis-dashboard
      └─ No binary (library)

    ↓

3. DEPLOY CONFIGURATIONS (NEW)
   ├─ Create ~/.config/core/
   ├─ Copy syntaxis-api-config.template.toml
   ├─ Copy configs/features/*.toml.template
   └─ Validate all configurations

    ↓

4. INSTALL WRAPPERS (NEW - Phase 2)
   ├─ Rename ~/.cargo/bin/workspace → ~/.cargo/bin/workspace.real
   ├─ Create wrapper script at ~/.cargo/bin/workspace
   │  └─ Finds config, sets up environment, calls .real binary
   └─ Same for syntaxis-tui, syntaxis-api

    ↓

5. REGISTER IN MANIFEST (NEW)
   ├─ Create .syntaxis/manifest.toml
   ├─ Track installed binaries (name, version, path)
   ├─ Track deployed configs (type, location)
   └─ Save installation metadata

    ↓

6. VERIFY INSTALLATION (NEW)
   └─ Test each wrapper, validate configs, print summary

    ↓

RESULT: Fully configured, ready-to-run binaries with tracked installation
```

### Configuration Management

```
Where configs are:
├─ syntaxis/syntaxis-api-config.template.toml ✅ Renamed, correct name
├─ syntaxis/configs/features/auth.toml.template
├─ syntaxis/configs/features/database.toml.template
├─ syntaxis/configs/features/cache.toml.template
├─ syntaxis/configs/features/health.toml.template
├─ syntaxis/configs/features/metrics.toml.template
├─ syntaxis/configs/features/multi_tenant.toml.template
├─ syntaxis/configs/features/rate_limit.toml.template
├─ syntaxis/configs/features/projects.toml.template        ✅ NEW
├─ syntaxis/configs/features/tasks.toml.template           ✅ NEW
├─ syntaxis/configs/features/phases.toml.template          ✅ NEW
└─ syntaxis/configs/features/audit.toml.template           ✅ NEW

Where configs end up:
├─ ~/.config/core/syntaxis-api.toml ✅ Standard location
└─ ~/.config/core/features/*.toml     ✅ Feature configs

How binaries find config:
├─ Wrapper script sets WORKSPACE_CONFIG_DIR
├─ Automatic find-config utility discovers:
│  ├─ ~/.config/core/
│  ├─ .project/
│  └─ .coder/
└─ Code respects environment variables

Installation tracking:
└─ .syntaxis/manifest.toml tracks:
   ├─ syntaxis-api version, path, installation date
   ├─ All deployed feature configs
   ├─ Configuration versions
   └─ Enable/disable status

Result:
✅ All configs deployed automatically
✅ Binaries can find configs
✅ Standard location (~/.config/)
✅ Installation fully tracked
```

### User Experience

```
$ just scripts-install
🔨 Installing syntaxis binaries...
✅ workspace: Installed successfully
✅ syntaxis-tui: Installed successfully
✅ syntaxis-api: Installed successfully

📋 Configurations deployed to:
  ~/.config/core/
  ├─ syntaxis-api.toml
  └─ features/
      ├─ auth.toml
      ├─ database.toml
      ├─ cache.toml
      ├─ health.toml
      ├─ metrics.toml
      ├─ multi_tenant.toml
      ├─ rate_limit.toml
      ├─ projects.toml
      ├─ tasks.toml
      ├─ phases.toml
      └─ audit.toml

✅ Registered 1 binary and 11 configurations in manifest

Next steps:
  workspace --version      # Test workspace CLI
  syntaxis-tui            # Launch TUI
  syntaxis-api            # Start REST API

$ workspace --version
syntaxis v0.1.0

Config loaded from: ~/.config/core/syntaxis-api.toml
Data directory: ~/.local/share/core/

$ nano ~/.config/core/syntaxis-api.toml
# User can easily edit configuration

$ syntaxis-api
Config loaded ✅
Features enabled:
  ✅ database (SQLite)
  ✅ auth (JWT)
  ✅ metrics (Prometheus)
  ✅ rate_limit (enabled)
  ✅ health (enabled)

Server listening on 0.0.0.0:8080
```

### Benefits of Proposed System

| Improvement | Before | After | Impact |
|-------------|--------|-------|--------|
| **Config Deployment** | Manual copy | Automatic | 🟢 Saves 5 mins |
| **Config Discovery** | User setup env var | Automatic with wrapper | 🟢 Just works |
| **Config Location** | Scattered | ~/.config/core/ | 🟢 Standard |
| **Installation Tracking** | Manual notes | manifest.toml | 🟢 Automatic audit |
| **Config Naming** | "syntaxis-api" (wrong) | "syntaxis-api" (correct) | 🟢 No confusion |
| **Workspace Features** | Missing (projects, tasks, etc.) | Complete templates | 🟢 Extensible |
| **User Onboarding** | Complex setup | Single command | 🟢 User friendly |
| **Environment Setup** | Manual variables | Wrapper handles | 🟢 Reliable |
| **Uninstallation** | Scattered cleanup | Manifest-tracked | 🟢 Clean removal |

---

## Implementation Phases

### Phase 1: Configuration Deployment ✅ Ready to Start
**Duration:** 1-2 weeks

```
Current: ❌ Configs not deployed
After:   ✅ Configs automatically deployed during installation
         ✅ Workspace-specific templates created
         ✅ Standard config location established
         ✅ Installation tracked in manifest
```

**What Gets Done:**
- Rename syntaxis-api → syntaxis-api
- Create projects, tasks, phases, audit templates
- Update installation script to copy configs
- Create installation guide

**User Impact:** "Configs are automatically deployed where they belong"

---

### Phase 2: Wrapper Scripts 🔜 Next
**Duration:** 1-2 weeks

```
Current: ❌ No wrapper scripts
After:   ✅ Wrapper scripts setup environment
         ✅ Config auto-discovery
         ✅ Env variables automatically set
         ✅ Binary execution just works
```

**What Gets Done:**
- Create wrapper script generator
- Rename binaries, create wrapper scripts
- Setup environment variables
- Document wrapper architecture

**User Impact:** "Binaries just work, no manual setup needed"

---

### Phase 3: Manifest Enhancement 🔜 Later
**Duration:** 1 week

```
Current: ❌ No version/config tracking
After:   ✅ Full installation audit trail
         ✅ Easy rollback capability
         ✅ Config version management
```

**What Gets Done:**
- Extend manifest.toml schema
- Add config validation
- Track configuration versions
- Support rollback

**User Impact:** "Can track and rollback installations"

---

### Phase 4: Documentation & Testing 🔜 Final
**Duration:** 1 week

```
Current: ❌ Scattered documentation
After:   ✅ Complete guides (Installation, Configuration, Wrapper)
         ✅ Integration tests
         ✅ Troubleshooting guide
```

**What Gets Done:**
- Create docs/installation-guide.md
- Create docs/configuration.md
- Create WRAPPER_GUIDE.md
- Add integration tests

**User Impact:** "Clear documentation for every scenario"

---

## Side-by-Side Comparison: CLI Usage

### Current System

```bash
# Step 1: Install (works)
$ just scripts-install
✅ workspace: Installed

# Step 2: Try to run (fails)
$ workspace --version
Error: Config not found at configs/default.toml

# Step 3: Manual setup (user must do this)
$ export CONFIG_PATH=/home/user/workspace.toml
$ cp syntaxis-api.toml /home/user/workspace.toml
$ nano /home/user/workspace.toml  # Edit

# Step 4: Run again (works if config is correct)
$ workspace --version
syntaxis v0.1.0

# User must repeat steps 3-4 for each command
$ export CONFIG_PATH=/home/user/workspace.toml && syntaxis-api
```

### Proposed System (After Phase 1)

```bash
# Step 1: Install (includes configs)
$ just scripts-install
✅ workspace: Installed
✅ Configs deployed to ~/.config/core/

# Step 2: Run immediately (just works)
$ workspace --version
syntaxis v0.1.0
Config: ~/.config/core/syntaxis-api.toml

# Step 3: Customize if needed
$ nano ~/.config/core/syntaxis-api.toml

# Step 4: Run again with custom config (automatically picked up)
$ syntaxis-api
Features loaded from: ~/.config/core/
Server listening on 0.0.0.0:8080

# No environment variables needed, no manual setup
```

---

## Architecture Summary

### Current
```
┌─────────────────┐
│  User runs CLI  │
└────────┬────────┘
         │
         ├─ Binary installed
         │
         └─ ❌ Config not found
              ❌ Env var not set
              ❌ Fails to start
```

### Proposed
```
┌─────────────────────────────────────┐
│  1. just scripts-install            │
│     (Compile + Install + Deploy)    │
└────────┬────────────────────────────┘
         │
         ├─ Binaries to ~/.cargo/bin/
         ├─ Configs to ~/.config/core/
         ├─ Wrappers setup environment
         └─ Manifest tracks installation

┌─────────────────────────────────────┐
│  2. User runs binary (e.g., syntaxis-api) │
└────────┬────────────────────────────┘
         │
         ├─ Wrapper script executes
         │  ├─ Find config file
         │  ├─ Set environment variables
         │  └─ Validate configuration
         │
         └─ Binary starts with config loaded
            ✅ Server running
            ✅ Features enabled
            ✅ Listening on port 8080
```

---

## Key Differences Table

| Aspect | Current | Proposed |
|--------|---------|----------|
| **Config Deployment** | Manual | Automatic during install |
| **Config Location** | User responsibility | ~/.config/core/ |
| **Config Discovery** | Hardcoded path | Automatic + env var support |
| **Environment Setup** | User must setup | Wrapper script does it |
| **Installation Tracking** | None | .syntaxis/manifest.toml |
| **Getting Started** | 5+ manual steps | 1 command (just scripts-install) |
| **Troubleshooting** | Complex | Clear error messages + docs |
| **Config Templates** | Incomplete | Complete with workspace features |

---

## Next Steps

### For Understanding
1. Read **INSTALLATION_ARCHITECTURE.md** for full design
2. Read **PHASE_1_IMPLEMENTATION.md** for first tasks
3. This document (quick reference)

### For Implementation
1. **Start Phase 1** when ready:
   - 30 mins: Rename config files
   - 1 hour: Create workspace feature templates
   - 1 hour: Update installation script
   - 1 hour: Create documentation
   - Total: ~4 hours per developer

2. **Phase 1 Success Criteria:**
   - ✅ Configs deployed to ~/.config/core/
   - ✅ Installation script updated
   - ✅ Templates created for projects, tasks, phases, audit
   - ✅ Documentation added
   - ✅ All tests pass

3. **Then Phase 2:**
   - Wrapper script implementation
   - Environment setup automation
   - Testing

---

**Document Version:** 1.0
**Status:** Ready to Share
**Created:** November 15, 2025

See **INSTALLATION_ARCHITECTURE.md** for full technical details.
See **PHASE_1_IMPLEMENTATION.md** for implementation checklist.