Quick installation guide for ClioDeck across different platforms.

## Platform Support

ClioDeck's architecture is designed to be cross-platform and supports:
- **Linux** - Fully tested and supported (AppImage and `.deb`, for **x86_64 and arm64**)
- **macOS** - Fully tested and supported (Intel and Apple Silicon)

Builds are **not code-signed**: macOS will refuse the app on first launch until you allow it explicitly (see the platform guide below).

**Note:** While the codebase is designed to run on all platforms, it has not been tested on Windows. It should be installable through a full build. Windows users may encounter issues. Contributions and testing reports are welcome!

---

## Detailed Installation Guides

For complete platform-specific installation instructions, see:

- **[Complete Linux installation guide](https://github.com/cliodeck/cliodeck-app/wiki/1.1-ClioDeck-Installation-%E2%80%90-Linux)**
  - Tested on Ubuntu, should work on Debian, Fedora, Arch Linux
  - AppImage and .deb packages
  - System dependencies and troubleshooting

- **[Complete macOS installation guide](https://github.com/cliodeck/cliodeck-app/wiki/1.2-ClioDeck-Installation-%E2%80%90-macOS)**
  - Intel and Apple Silicon support
  - Homebrew dependencies
  - DMG installation and security settings

---

## Prerequisites

Before installing ClioDeck, ensure you have:

- **Node.js** 20+ and npm 10+
- **Python** 3.11+ (for topic modeling services)
- **Pandoc** + **XeLaTeX** (for PDF export)
- **Ollama** with models — or skip Ollama entirely and use the small embedded models instead (see below):
  - `nomic-embed-text` (embeddings, 768 dimensions). `mxbai-embed-large` is a valid alternative, but ClioDeck does **not** fall back to it automatically — whichever you pick in Settings is the one used.
  - `gemma2:2b` (chat - recommended for generation, but cannot use tools — see the note below)

To benefit from the PDF and word export features, installing pandoc and xelatex is necessary.

**Fully offline generation, no Ollama:** download the embedded generation model (Qwen2.5-0.5B, ~470 MB) from Settings → LLM. A fully offline **RAG** workflow — embeddings included, not just generation — is available from Settings since RC4, which added an Embeddings section exposing the provider and the embedded model. See the [Embedded LLM Guide](https://github.com/cliodeck/cliodeck-app/wiki/1.7-Embedded-LLM-Guide).

**Tool use:** `gemma2:2b` can't call tools (search your corpus, use MCP servers) inside Brainstorm — Ollama only advertises tool support for a specific whitelist (`qwen3:8b/14b/32b`, `ministral-3:8b/14b`, `mistral-nemo`).

---

## Quick Installation

### Linux (AppImage)

```bash
# Download the AppImage from releases
chmod +x ClioDeck-*.AppImage

# Launch
./ClioDeck-*.AppImage
```

(`scripts/install-desktop.sh` exists in the source repository but is not bundled into the AppImage release asset — it's only usable if you've cloned the repo. Note: the `.desktop` entry it generates launches the AppImage with `--no-sandbox`, a common AppImage/Electron compatibility workaround — but it does disable Chromium's OS-level sandbox for that launch method specifically, on top of whatever the app's own renderer `sandbox: true` setting provides. Launching the AppImage directly, as in the command above, does not add this flag.)

### Linux (Debian/Ubuntu .deb)

```bash
sudo dpkg -i cliodeck_*.deb
sudo apt-get install -f  # Install missing dependencies
```

### macOS (DMG)

```bash
# Download DMG from releases
open ClioDeck-*.dmg

# Drag ClioDeck to Applications folder
# First launch: System Preferences → Security & Privacy → Open Anyway
```
---

## Installing Ollama and Models

### Linux

```bash
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull nomic-embed-text
ollama pull gemma2:2b
```

### macOS

```bash
brew install ollama
brew services start ollama
ollama pull nomic-embed-text
ollama pull gemma2:2b
```

---

## Building from Source

For developers or if pre-built packages are not available:

```bash
# Clone repository
git clone https://github.com/cliodeck/cliodeck-app.git
cd cliodeck-app

# Install dependencies (native modules are rebuilt for Electron's ABI
# automatically by the postinstall script — no separate step needed)
npm install

# Build the application
npm run build

# Launch in development mode
npm start

# Or build packages for distribution
npm run build:linux    # AppImage + .deb
npm run build:mac      # DMG (x64 + arm64)
npm run build:win      # NSIS installer (untested)
```

See [Build and Deployment Guide](https://github.com/cliodeck/cliodeck-app/wiki/2.1-Build-and-Deployment-Guide) for complete build instructions.

---

## First Launch Configuration

The first time you open **Settings**, ClioDeck checks the Ollama connection (http://localhost:11434) — this happens when the Settings panel mounts, not automatically at app launch.

Creating a project will create project structure in your chosen folder and initialize `.cliodeck/brain.db` — the shared SQLite store for PDF vectors, Tropy primary sources, and research history.

Configure in **Settings**:
- LLM backend (Ollama URL and models)
- RAG parameters (topK, similarity threshold)
- Zotero integration (optional)
- Download the embedded model (for small configs)
- Install the BERTopic venv
- Choose language (French / English / German)

---

## Troubleshooting

### Ollama not responding

```bash
# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama manually if needed
ollama serve
```

### Native module errors (better-sqlite3, hnswlib-node)

```bash
# Rebuild native modules for your platform
cd /path/to/cliodeck-app
npm run rebuild:native
```

### Missing Pandoc or XeLaTeX

PDF export requires both Pandoc and XeLaTeX. See platform-specific guides for installation instructions.

---

## Getting Help

- **Installation Issues:** See platform-specific guides ([linux](https://github.com/cliodeck/cliodeck-app/wiki/1.1-ClioDeck-Installation-%E2%80%90-Linux), [macos](https://github.com/cliodeck/cliodeck-app/wiki/1.2-ClioDeck-Installation-%E2%80%90-macOS))
- **Build Issues:** See [Build and Deployment Guide](https://github.com/cliodeck/cliodeck-app/wiki/2.1-Build-and-Deployment-Guide)
- **General Questions:** Open an issue on [GitHub](https://github.com/cliodeck/cliodeck-app/issues)
- **Architecture Documentation:** See [Technical Architecture](https://github.com/cliodeck/cliodeck-app/wiki/2.-Technical-Architecture)

---

## Uninstallation

### Linux (AppImage)

```bash
rm ~/.local/share/applications/cliodeck.desktop
rm -rf ~/.local/share/icons/hicolor/*/apps/cliodeck.png
update-desktop-database ~/.local/share/applications/
```

### Linux (.deb)

```bash
sudo apt remove cliodeck
```

### macOS

```bash
rm -rf /Applications/ClioDeck.app
rm -rf ~/Library/Application\ Support/cliodeck
```

---

**Note:** Your project data (`.md` files, PDFs, `.cliodeck/` folders) is stored in your project directories and is not automatically deleted during uninstallation.