aiwg/docs/troubleshooting/setup-issues.md

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

# Setup Issues

Problems during AIWG installation or project setup.

## AIWG Installation Not Found

**Symptoms**: "AIWG not found", "aiwg command not found"

**Cause**: AIWG CLI not installed or not in PATH.

**Solution**:

```bash
# Install AIWG via npm (recommended)
npm install -g aiwg

# Verify
aiwg -version
```

**Bleeding edge:** `curl -fsSL https://raw.githubusercontent.com/jmagly/ai-writing-guide/main/tools/install/install.sh | bash`

## Installation Path Issues

**Symptoms**: Commands work but templates/agents not found.

**Cause**: AIWG installed in non-standard location.

**Solution**:

```bash
# Check where AIWG is installed
ls ~/.local/share/ai-writing-guide/

# If installed elsewhere, set environment variable
export AIWG_ROOT=/path/to/ai-writing-guide

# Add to shell profile for persistence
echo 'export AIWG_ROOT=/path/to/ai-writing-guide' >> ~/.bashrc
```

## Corrupt Installation

**Symptoms**: Partial files, missing directories, strange errors.

**Cause**: Interrupted install or git issues.

**Solution**:

```bash
# Force clean reinstall
aiwg -reinstall

# Or manual cleanup
rm -rf ~/.local/share/ai-writing-guide
npm install -g aiwg
```

## Permission Denied

**Symptoms**: "Permission denied" during install or commands.

**Cause**: Insufficient permissions on install directory.

**Solution**:

```bash
# Fix permissions on install directory
chmod -R u+rwX ~/.local/share/ai-writing-guide/

# If installed system-wide (not recommended)
sudo chown -R $USER:$USER /usr/local/share/ai-writing-guide/
```

## Shell Alias Not Working

**Symptoms**: `aiwg` command not found after install.

**Cause**: Shell aliases not loaded.

**Solution**:

```bash
# For bash
source ~/.bash_aliases
# Or
source ~/.bashrc

# For zsh
source ~/.zshrc

# Verify alias exists
alias aiwg
```

## Related

- [Deployment Issues](#ts-deployment) - Agent/command deployment problems
- [Path Issues](#ts-paths) - Template and file path errors