syntaxis/docs/installation-guide.md

Installation Guide

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

Quick Start

Install all binaries with one command:

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

just scripts-install all

Installs workspace, syntaxis-tui, and syntaxis-dashboard with configurations.

Install Specific Binary

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

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

just scripts-install status

Shows which binaries are installed and their locations.

List Available Binaries

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

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

[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

# 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

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

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

   just scripts-install status
   

2. Read configuration guide:

   cat docs/configuration.md
   

3. Use the CLI:

   workspace --help
   workspace project list
   

4. Launch the TUI:

   syntaxis-tui
   

5. Start the web dashboard:

   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