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

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

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