ai-lsc/quickstart.md

# Quickstart Guide

Get AI Local Stack Control up and running in under 5 minutes.

## Prerequisites

| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| OS | Arch Linux | Arch Linux / EndeavourOS |
| Python | 3.11 | 3.12+ |
| RAM | 8 GB | 16 GB+ (for LLM inference) |
| Disk | 4 GB free | 20 GB+ (for model storage) |
| GPU | None | NVIDIA (CUDA) or AMD (ROCm) |

## Installation

### Option 1: Bootstrap Script (Recommended)

```bash
# Clone the repository
git clone https://github.com/your-username/ai-lsc.git
cd ai-lsc

# Run the bootstrap script (installs system + Python deps)
chmod +x bootstrap.sh
./bootstrap.sh

# Launch the application
python -m ai_lsc
```

### Option 2: Manual Install

#### Step 1: System Dependencies

```bash
# Core packages (Arch Linux)
sudo pacman -S python python-pip python-pyqt6 pyside6 \
    git tmux ripgrep fd tree-sitter sqlite redis

# Optional: GPU support
sudo pacman -S cuda        # NVIDIA
# sudo pacman -S rocm-hip-sdk  # AMD

# Optional: Container runtimes
sudo pacman -S podman docker
# Optional: LXC support
sudo pacman -S lxc lxcfs
```

#### Step 2: Python Dependencies

```bash
cd ai-lsc

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate

# Install PySide6 and dependencies
pip install PySide6
pip install -e .
```

#### Step 3: Verify Installation

```bash
# Check that the registry loads correctly
python -c "
from ai_lsc import DEFAULT_REGISTRY, validate_registry
errors = validate_registry(DEFAULT_REGISTRY)
print(f'Registry loaded: {len(DEFAULT_REGISTRY)} tools')
print(f'Validation errors: {len(errors)}')
"

# Expected output:
# Registry loaded: 115 tools
# Validation errors: 0
```

#### Step 4: Launch

```bash
python -m ai_lsc
```

## First Launch

When you launch AI-LSC for the first time, you will see the **Stack Template Wizard**. This is your entry point for configuring your AI stack.

### Choosing a Template

| Template | Best For | Tool Count |
|----------|----------|-----------|
| Claude Code Setup | Claude Code development workflow | 11 |
| Free Claude Code | Minimal Claude Code environment | 4 |
| Local LLM Lab | Self-hosted LLM experimentation | 10 |
| SaaS Integrations | Production deployment with SSL/CDN | 12 |

### Manual Configuration

If you prefer to build your stack from scratch:

1. Select **Create From Scratch** in the wizard
2. Navigate to the **Infrastructure** section in the sidebar
3. Expand each layer and toggle tools on/off
4. Use the **IPC Stack** tab to validate dependencies
5. Click **Compile** to save your stack configuration

## Post-Setup

### Installing a Base LLM

Most tools depend on Ollama as the local LLM runtime:

```bash
# Install Ollama (if not already installed)
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3
ollama pull codellama    # Good for coding assistance
ollama pull mistral      # Lightweight general-purpose
```

### Starting Services

After configuring your stack in the IPC Stack tab:

1. Click **Compile** to save the stack configuration
2. Switch to the **Monitor** tab
3. Click **Start All** or start individual services
4. Check service status indicators (green = running)

### Connecting the Chat Console

Once Ollama is running:

1. Navigate to the **Chat** section
2. Select a model from the dropdown (e.g., `llama3`, `codellama`)
3. Start chatting with your local AI assistant

## Common Tasks

### Adding a New Tool

1. Identify the target layer in `registry/layers/`
2. Add the tool entry following the canonical schema
3. Restart the application — the tool appears automatically

### Exporting to Containers

1. Open **Deployment Targets** from the sidebar
2. Select your backend: Podman, Docker, or LXC
3. Click **Export** to generate configuration files
4. Deploy with `podman compose up` or `lxc-launch.sh`

### Managing LXC Containers

```bash
# Create a container from exported config
sudo lxc-create -n ollama -f ollama.conf

# Start the container
sudo lxc-start -n ollama

# Attach to the container console
sudo lxc-attach -n ollama

# Freeze/unfreeze
sudo lxc-freeze -n ollama
sudo lxc-unfreeze -n ollama

# Destroy
sudo lxc-stop -n ollama
sudo lxc-destroy -n ollama
```

## Troubleshooting

### PySide6 Import Error

```
ModuleNotFoundError: No module named 'PySide6'
```

**Fix:** Install PySide6: `pip install PySide6`

### Registry Loading Errors

```
ERROR: Failed to load layer file: SyntaxError
```

**Fix:** Validate layer files:
```bash
python3 -c "
import ast, os
for f in os.listdir('ai_lsc/registry/layers'):
    if f.endswith('.py') and f != '__init__.py':
        ast.parse(open(f'ai_lsc/registry/layers/{f}').read())
        print(f'{f}: OK')
"
```

### Service Won't Start

1. Check the **Monitor** tab for error messages
2. Verify the tool is installed: `which <tool_name>`
3. Check launcher command in the registry entry
4. For systemd services: `systemctl --user status <service>`

### Ollama Connection Refused

1. Ensure Ollama is running: `ollama serve` or `systemctl --user start ollama`
2. Check port: `curl http://localhost:11434/api/tags`
3. Verify the endpoint in Settings matches your Ollama port

## Next Steps

- Explore the **Infrastructure** section to understand the 13-layer architecture
- Try different **Stack Templates** to find the right combination for your workflow
- Set up the **Skills Console** to extend your tool capabilities
- Use **Code Analysis** to inspect and understand your project dependencies