# Familiar Installer

**One-click installation for Windows, macOS, and Linux**

## Download

| Platform | Download | Size |
|----------|----------|------|
| Windows 10/11 | [Familiar-Setup.exe](https://github.com/your-org/familiar/releases/latest/download/Familiar-Setup.exe) | ~25 MB |
| macOS (Intel/ARM) | [Familiar-Setup.dmg](https://github.com/your-org/familiar/releases/latest/download/Familiar-Setup.dmg) | ~20 MB |
| Linux (x64) | [Familiar-Setup.AppImage](https://github.com/your-org/familiar/releases/latest/download/Familiar-Setup-x86_64.AppImage) | ~22 MB |

## Installation

### Windows

1. Download `Familiar-Setup.exe`
2. Double-click to run
3. Follow the setup wizard (5 steps, ~3 minutes)
4. Familiar starts automatically

**Note:** Windows may show a SmartScreen warning for unsigned builds. Click "More info" → "Run anyway".

### macOS

1. Download `Familiar-Setup.dmg`
2. Double-click to open
3. Drag to Applications (or run directly)
4. Follow the setup wizard

**Note:** If you see "cannot be opened because it is from an unidentified developer":
- Right-click → Open → Open (first time only)
- Or: System Settings → Privacy & Security → Open Anyway

### Linux

1. Download `Familiar-Setup-x86_64.AppImage`
2. Make executable: `chmod +x Familiar-Setup-x86_64.AppImage`
3. Double-click or run: `./Familiar-Setup-x86_64.AppImage`
4. Follow the setup wizard

## Setup Wizard

The installer walks you through 5 simple steps:

```
┌─────────────────────────────────────────────────┐
│  1. Welcome          - Overview of features     │
│  2. License          - MIT license agreement    │
│  3. Location         - Where to install         │
│  4. AI Provider      - API key setup            │
│  5. Channels         - Telegram, Discord, etc.  │
│  6. Installing...    - Automatic setup          │
│  7. Complete!        - Ready to use             │
└─────────────────────────────────────────────────┘
```

**Total time: ~3-5 minutes**

## What Gets Installed

```
~/.local/share/familiar/     (Linux)
~/Library/Application Support/Familiar/    (macOS)
%LOCALAPPDATA%\Familiar\     (Windows)
├── venv/                   # Python virtual environment
├── familiar/                # Application code
├── data/
│   ├── sessions/          # Encrypted sessions
│   ├── memory/            # Persistent memory
│   ├── history/           # Conversation history
│   ├── audit/             # Audit logs
│   └── backups/           # Automatic backups
├── config.yaml            # Configuration
└── .env                   # API keys (encrypted)
```

## Requirements

- **OS:** Windows 10+, macOS 11+, Ubuntu 20.04+ (or similar)
- **RAM:** 2 GB minimum, 4 GB recommended
- **Disk:** 500 MB for installation
- **Network:** Internet access for API calls

## API Keys

You'll need an API key from at least one provider:

| Provider | Get Key | Cost |
|----------|---------|------|
| [Anthropic](https://console.anthropic.com/) | Claude API | Pay-per-use |
| [OpenAI](https://platform.openai.com/api-keys) | GPT API | Pay-per-use |
| [Ollama](https://ollama.com/) | Local LLM | Free (requires 8GB+ RAM) |

## After Installation

Familiar runs in the background. Access it via:

- **System tray icon** (🦔) - Click to open
- **Command line** - `familiar` or `familiar chat`
- **Telegram/Discord** - If configured during setup

## Uninstall

### Windows
Settings → Apps → Familiar → Uninstall

Or delete: `%LOCALAPPDATA%\Familiar`

### macOS
Delete from Applications

And remove: `~/Library/Application Support/Familiar`

### Linux
Delete the AppImage

And remove: `~/.local/share/familiar` and `~/.familiar`

## Troubleshooting

### "Python not found"
The installer includes its own Python environment. If you see this error, try:
- Windows: Install Python from [python.org](https://python.org)
- macOS: `brew install python3`
- Linux: `sudo apt install python3 python3-venv`

### "API key invalid"
- Check for extra spaces when copying
- Ensure you're using the right provider's key format
- Anthropic keys start with `sk-ant-`
- OpenAI keys start with `sk-`

### "Permission denied"
- Windows: Run as Administrator
- macOS/Linux: Check file permissions in install directory

### More help
- [Documentation](https://docs.familiar.ai)
- [Discord Community](https://discord.gg/familiar)
- [GitHub Issues](https://github.com/your-org/familiar/issues)

## Building from Source

```bash
# Clone repo
git clone https://github.com/your-org/familiar.git
cd familiar

# Install build tools
pip install pyinstaller pillow

# Build for current platform
cd familiar/installer
python build_installer.py
```

Output will be in `dist/<platform>/`

## Security

- All executables are built in GitHub Actions (reproducible)
- SHA256 checksums provided for verification
- Windows/macOS builds are code-signed (when certificates available)
- API keys are encrypted at rest using Fernet (AES-128)
- No telemetry or data collection

## License

MIT License - See [LICENSE](../LICENSE)
